free-coding-models 0.3.24 → 0.3.26

package/src/mouse.js

@@ -0,0 +1,186 @@
+/**
+ * @file mouse.js
+ * @description Terminal mouse tracking infrastructure for the TUI.
+ *
+ * @details
+ *   Provides SGR (mode 1006) mouse event parsing and tracking enable/disable sequences.
+ *   SGR mode is preferred over X10/normal because it supports coordinates > 223
+ *   and distinguishes press vs release events cleanly.
+ *
+ *   Mouse events arrive as raw escape sequences on stdin when tracking is enabled:
+ *     Press:   \x1b[<Btn;X;YM
+ *     Release: \x1b[<Btn;X;Ym
+ *
+ *   Button encoding (Btn field):
+ *     0 = left click, 1 = middle click, 2 = right click
+ *     32 = left drag, 33 = middle drag, 34 = right drag
+ *     64 = scroll up, 65 = scroll down
+ *     +4 = Shift held, +8 = Meta/Alt held, +16 = Control held
+ *
+ *   Coordinates are 1-based in SGR mode (col 1, row 1 = top-left).
+ *
+ *   ⚙️ Key configuration:
+ *   - MOUSE_ENABLE: appended to ALT_ENTER to start mouse tracking on TUI init
+ *   - MOUSE_DISABLE: prepended to ALT_LEAVE to stop mouse tracking on TUI exit
+ *   - DOUBLE_CLICK_MS: maximum gap between two clicks to count as double-click
+ *
+ * @functions
+ *   → parseMouseEvent(data)      — Parse raw stdin buffer into structured mouse event
+ *   → createMouseHandler(opts)   — Create a stdin 'data' listener that emits mouse events
+ *
+ * @exports
+ *   MOUSE_ENABLE, MOUSE_DISABLE,
+ *   parseMouseEvent, createMouseHandler
+ *
+ * @see src/app.js          — wires the mouse data listener alongside keypress
+ * @see src/key-handler.js  — receives parsed mouse events for UI actions
+ * @see src/constants.js    — ALT_ENTER / ALT_LEAVE include mouse sequences
+ */
+
+// 📖 SGR mouse mode (1006) sends coordinates as decimal numbers terminated by M/m,
+// 📖 supporting terminals wider than 223 columns (unlike X10 mode).
+// 📖 Mode 1000 = basic button tracking (press + release).
+// 📖 Mode 1002 = button-event tracking (adds drag reporting).
+// 📖 Mode 1003 = any-event tracking (adds mouse movement) — intentionally NOT used
+// 📖 because movement floods stdin and we don't need hover.
+export const MOUSE_ENABLE  = '\x1b[?1000h\x1b[?1002h\x1b[?1006h'
+export const MOUSE_DISABLE = '\x1b[?1006l\x1b[?1002l\x1b[?1000l'
+
+// 📖 Double-click detection window in milliseconds.
+const DOUBLE_CLICK_MS = 400
+
+// 📖 Regex to match SGR mouse sequences: \x1b[<Btn;Col;Row[Mm]
+// 📖 Groups: 1=button, 2=column(x), 3=row(y), 4=M(press)|m(release)
+const SGR_MOUSE_RE = /\x1b\[<(\d+);(\d+);(\d+)([Mm])/g
+
+/**
+ * 📖 parseMouseEvents: Extract all SGR mouse events from a raw stdin data chunk.
+ * 📖 A single data chunk can contain multiple mouse events (e.g. rapid scrolling).
+ * @param {string|Buffer} data — raw stdin data
+ * @returns {Array<{button: number, x: number, y: number, type: string, shift: boolean, meta: boolean, ctrl: boolean}>}
+ */
+export function parseMouseEvents(data) {
+  const str = typeof data === 'string' ? data : data.toString('utf8')
+  const events = []
+  let match
+
+  // 📖 Reset regex lastIndex for reuse
+  SGR_MOUSE_RE.lastIndex = 0
+
+  while ((match = SGR_MOUSE_RE.exec(str)) !== null) {
+    const rawBtn = parseInt(match[1], 10)
+    const x = parseInt(match[2], 10) // 📖 1-based column
+    const y = parseInt(match[3], 10) // 📖 1-based row
+    const isRelease = match[4] === 'm'
+
+    // 📖 Extract modifier keys from the button field
+    const shift = !!(rawBtn & 4)
+    const meta  = !!(rawBtn & 8)
+    const ctrl  = !!(rawBtn & 16)
+
+    // 📖 Strip modifier bits to get the base button
+    const baseBtn = rawBtn & ~(4 | 8 | 16)
+
+    let type, button
+
+    if (baseBtn === 64) {
+      type = 'scroll-up'
+      button = 'scroll-up'
+    } else if (baseBtn === 65) {
+      type = 'scroll-down'
+      button = 'scroll-down'
+    } else if (baseBtn >= 32 && baseBtn <= 34) {
+      type = 'drag'
+      button = baseBtn === 32 ? 'left' : baseBtn === 33 ? 'middle' : 'right'
+    } else if (isRelease) {
+      type = 'release'
+      button = baseBtn === 0 ? 'left' : baseBtn === 1 ? 'middle' : 'right'
+    } else {
+      type = 'press'
+      button = baseBtn === 0 ? 'left' : baseBtn === 1 ? 'middle' : 'right'
+    }
+
+    events.push({ type, button, x, y, shift, meta, ctrl })
+  }
+
+  return events
+}
+
+/**
+ * 📖 containsMouseSequence: Quick check if a data chunk contains any SGR mouse sequence.
+ * 📖 Used to prevent the keypress handler from processing mouse data as keypresses.
+ * @param {string|Buffer} data
+ * @returns {boolean}
+ */
+export function containsMouseSequence(data) {
+  const str = typeof data === 'string' ? data : data.toString('utf8')
+  return str.includes('\x1b[<')
+}
+
+/**
+ * 📖 createMouseHandler: Factory that returns a stdin 'data' callback for mouse events.
+ * 📖 Handles double-click detection internally by tracking the last click position/time.
+ *
+ * @param {object} opts
+ * @param {function} opts.onMouseEvent — callback receiving structured mouse events:
+ *   { type: 'click'|'double-click'|'scroll-up'|'scroll-down'|'drag', button, x, y, shift, meta, ctrl }
+ * @returns {function} — attach to process.stdin.on('data', returnedFn)
+ */
+export function createMouseHandler({ onMouseEvent }) {
+  // 📖 Double-click tracking state
+  let lastClickX = -1
+  let lastClickY = -1
+  let lastClickTime = 0
+
+  return (data) => {
+    const str = typeof data === 'string' ? data : data.toString('utf8')
+
+    // 📖 Only process data that contains mouse sequences
+    if (!str.includes('\x1b[<')) return
+
+    const events = parseMouseEvents(str)
+
+    for (const evt of events) {
+      // 📖 Scroll events are emitted immediately (no press/release distinction)
+      if (evt.type === 'scroll-up' || evt.type === 'scroll-down') {
+        onMouseEvent(evt)
+        continue
+      }
+
+      // 📖 Drag events forwarded as-is
+      if (evt.type === 'drag') {
+        onMouseEvent(evt)
+        continue
+      }
+
+      // 📖 Only emit click on release (not press) to match expected click semantics.
+      // 📖 This prevents double-firing and feels more natural to the user.
+      if (evt.type === 'release' && evt.button === 'left') {
+        const now = Date.now()
+        const isDoubleClick =
+          (now - lastClickTime) < DOUBLE_CLICK_MS &&
+          evt.x === lastClickX &&
+          evt.y === lastClickY
+
+        if (isDoubleClick) {
+          onMouseEvent({ ...evt, type: 'double-click' })
+          // 📖 Reset so a third click doesn't count as another double-click
+          lastClickTime = 0
+          lastClickX = -1
+          lastClickY = -1
+        } else {
+          onMouseEvent({ ...evt, type: 'click' })
+          lastClickTime = now
+          lastClickX = evt.x
+          lastClickY = evt.y
+        }
+        continue
+      }
+
+      // 📖 Right-click and middle-click: emit on release
+      if (evt.type === 'release') {
+        onMouseEvent({ ...evt, type: 'click' })
+      }
+    }
+  }
+}

package/src/overlays.js

@@ -14,7 +14,7 @@
  *   📖 Feedback overlay (I key) combines feature requests + bug reports in one left-aligned input
  *
  *   → Functions:
- *   - `createOverlayRenderers` — returns renderer + analysis helpers
+ *   - `createOverlayRenderers` — returns renderer + analysis helpers + overlayLayout
  *
  * @exports { createOverlayRenderers }
  * @see ./key-handler.js — handles keypresses for all overlay interactions
@@ -85,6 +85,29 @@ export function createOverlayRenderers(state, deps) {
     return lines
   }
 
+  // 📖 Overlay layout tracking: records cursor-to-line mappings and scroll offsets
+  // 📖 so the mouse handler can map terminal click coordinates → overlay cursor positions.
+  // 📖 Updated each render frame by the active overlay renderer.
+  const overlayLayout = {
+    settingsCursorToLine: {},   // 📖 cursor index → line index in pre-scroll lines array
+    settingsScrollOffset: 0,   // 📖 current scroll offset applied by sliceOverlayLines
+    settingsMaxRow: 0,         // 📖 maximum valid settingsCursor index
+    installEndpointsCursorToLine: {},
+    installEndpointsScrollOffset: 0,
+    installEndpointsMaxRow: 0,
+    commandPaletteCursorToLine: {},
+    commandPaletteScrollOffset: 0,
+    commandPaletteBodyStartRow: 0, // 📖 1-based terminal row where CP results begin
+    commandPaletteBodyRows: 0,
+    commandPaletteLeft: 0,
+    commandPaletteRight: 0,
+    commandPaletteTop: 0,
+    commandPaletteBottom: 0,
+    changelogCursorToLine: {},
+    changelogScrollOffset: 0,
+    recommendOptionRows: {},       // 📖 option index → 1-based terminal row (questionnaire phase)
+  }
+
   // ─── Settings screen renderer ─────────────────────────────────────────────
   // 📖 renderSettings: Draw the settings overlay in the alt screen buffer.
   // 📖 Shows all providers with their API key (masked) + enabled state.
@@ -287,6 +310,11 @@ export function createOverlayRenderers(state, deps) {
     const { visible, offset } = sliceOverlayLines(lines, state.settingsScrollOffset, state.terminalRows)
     state.settingsScrollOffset = offset
 
+    // 📖 Mouse support: record layout so click handler can map Y → settingsCursor
+    overlayLayout.settingsCursorToLine = { ...cursorLineByRow }
+    overlayLayout.settingsScrollOffset = offset
+    overlayLayout.settingsMaxRow = changelogViewRowIdx
+
     const tintedLines = tintOverlayLines(visible, themeColors.overlayBgSettings, state.terminalCols)
     const cleared = tintedLines.map(l => l + EL)
     return cleared.join('\n')
@@ -451,6 +479,114 @@ export function createOverlayRenderers(state, deps) {
     return cleared.join('\n')
   }
 
+  // ─── Installed Models Manager overlay renderer ─────────────────────────────
+  // 📖 renderInstalledModels displays all models configured in external tools
+  // 📖 Shows tool configs, model lists, and provides actions (Launch, Disable, Reinstall)
+  function renderInstalledModels() {
+    const EL = '\x1b[K'
+    const lines = []
+    const cursorLineByRow = {}
+
+    lines.push('')
+    lines.push(`  ${themeColors.accent('🚀')} ${themeColors.accentBold('free-coding-models')} ${themeColors.dim(`v${LOCAL_VERSION}`)}`)
+    lines.push(`  ${themeColors.textBold('🗂️  Installed Models Manager')}`)
+    lines.push('')
+    lines.push(themeColors.dim('  — models configured in your tools'))
+
+    if (state.installedModelsErrorMsg) {
+      lines.push(`  ${themeColors.warning(state.installedModelsErrorMsg)}`)
+    }
+
+    if (state.installedModelsErrorMsg === 'Scanning...') {
+      lines.push(themeColors.dim('  Scanning tool configs, please wait...'))
+      const targetLine = 5
+      state.installedModelsScrollOffset = keepOverlayTargetVisible(
+        state.installedModelsScrollOffset,
+        targetLine,
+        lines.length,
+        state.terminalRows
+      )
+      const { visible, offset } = sliceOverlayLines(lines, state.installedModelsScrollOffset, state.terminalRows)
+      state.installedModelsScrollOffset = offset
+
+      overlayLayout.installedModelsCursorToLine = cursorLineByRow
+      overlayLayout.installedModelsScrollOffset = offset
+
+      const tintedLines = tintOverlayLines(visible, themeColors.overlayBgSettings, state.terminalCols)
+      const cleared = tintedLines.map((l) => l + EL)
+      return cleared.join('\n')
+    }
+
+    lines.push('')
+
+    const scanResults = state.installedModelsData || []
+
+    if (scanResults.length === 0) {
+      lines.push(themeColors.dim('  No tool configs found.'))
+      lines.push(themeColors.dim('  Install a tool (Goose, Crush, Aider, etc.) to get started.'))
+    } else {
+      let globalIdx = 0
+
+      for (const toolResult of scanResults) {
+        const { toolMode, toolLabel, toolEmoji, configPath, isValid, hasManagedMarker, models } = toolResult
+
+        lines.push('')
+        const isCursor = globalIdx === state.installedModelsCursor
+
+        const statusIcon = isValid ? themeColors.successBold('✅') : themeColors.errorBold('⚠️')
+        const toolHeader = `${bullet(isCursor)}${toolEmoji} ${themeColors.textBold(toolLabel)} ${statusIcon}`
+        cursorLineByRow[globalIdx++] = lines.length
+        lines.push(isCursor ? themeColors.bgCursor(toolHeader) : toolHeader)
+
+        const configShortPath = configPath.replace(process.env.HOME || homedir(), '~')
+        lines.push(`     ${themeColors.dim(configShortPath)}`)
+
+        if (!isValid) {
+          lines.push(themeColors.dim('     ⚠️  Config invalid or missing'))
+        } else if (models.length === 0) {
+          lines.push(themeColors.dim('     No models configured'))
+        } else {
+          const managedBadge = hasManagedMarker ? themeColors.info('• Managed by FCM') : themeColors.dim('• External config')
+          lines.push(`     ${themeColors.success(`${models.length} model${models.length > 1 ? 's' : ''} configured`)}  ${managedBadge}`)
+
+          for (const model of models) {
+            const isModelCursor = globalIdx === state.installedModelsCursor
+            const tierBadge = model.tier !== '-' ? themeColors.info(model.tier.padEnd(2)) : themeColors.dim('  ')
+            const externalBadge = model.isExternal ? themeColors.dim('[external]') : ''
+
+            const modelRow = `     • ${model.label} ${tierBadge} ${externalBadge}`
+            cursorLineByRow[globalIdx++] = lines.length
+            lines.push(isModelCursor ? themeColors.bgCursor(modelRow) : modelRow)
+
+            if (isModelCursor) {
+              lines.push(`        ${themeColors.dim('[Enter] Launch  [D] Disable')}`)
+            }
+          }
+        }
+      }
+    }
+
+    lines.push('')
+    lines.push(themeColors.dim('  ↑↓ Navigate  Enter=Launch  D=Disable  Esc=Close'))
+
+    const targetLine = cursorLineByRow[state.installedModelsCursor] ?? 0
+    state.installedModelsScrollOffset = keepOverlayTargetVisible(
+      state.installedModelsScrollOffset,
+      targetLine,
+      lines.length,
+      state.terminalRows
+    )
+    const { visible, offset } = sliceOverlayLines(lines, state.installedModelsScrollOffset, state.terminalRows)
+    state.installedModelsScrollOffset = offset
+
+    overlayLayout.installedModelsCursorToLine = cursorLineByRow
+    overlayLayout.installedModelsScrollOffset = offset
+
+    const tintedLines = tintOverlayLines(visible, themeColors.overlayBgSettings, state.terminalCols)
+    const cleared = tintedLines.map((l) => l + EL)
+    return cleared.join('\n')
+  }
+
   // ─── Missing-tool install confirmation overlay ────────────────────────────
   // 📖 renderToolInstallPrompt keeps the user inside the TUI long enough to
   // 📖 confirm the auto-install, then the key handler exits the alt screen and
@@ -684,6 +820,18 @@ export function createOverlayRenderers(state, deps) {
     const top = Math.max(1, Math.floor((terminalRows - panelHeight) / 2) + 1)
     const left = Math.max(1, Math.floor((terminalCols - panelOuterWidth) / 2) + 1)
 
+    // 📖 Mouse support: record CP layout so clicks inside the modal can select items.
+    // 📖 Body rows start after 2 blank-padding lines + headerLines (3).
+    const bodyStartRow = top + 2 + headerLines.length // 📖 1-based terminal row of first body line
+    overlayLayout.commandPaletteCursorToLine = { ...cursorLineByRow }
+    overlayLayout.commandPaletteScrollOffset = state.commandPaletteScrollOffset
+    overlayLayout.commandPaletteBodyStartRow = bodyStartRow
+    overlayLayout.commandPaletteBodyRows = bodyRows
+    overlayLayout.commandPaletteLeft = left
+    overlayLayout.commandPaletteRight = left + panelOuterWidth - 1
+    overlayLayout.commandPaletteTop = top
+    overlayLayout.commandPaletteBottom = top + panelHeight - 1
+
     const tintedLines = paddedPanelLines.map((line) => {
       const padded = padEndDisplay(line, panelOuterWidth)
       return themeColors.overlayBgCommandPalette(padded)
@@ -861,6 +1009,10 @@ export function createOverlayRenderers(state, deps) {
         const opt = q.options[i]
         const isCursor = i === state.recommendCursor
         const label = isCursor ? themeColors.textBold(opt.label) : themeColors.text(opt.label)
+        // 📖 Mouse support: record the 1-based terminal row of each option
+        // 📖 lines.length is the 0-based index → +1 = 1-based row
+        overlayLayout.recommendOptionRows = overlayLayout.recommendOptionRows || {}
+        overlayLayout.recommendOptionRows[i] = lines.length + 1
         lines.push(`${bullet(isCursor)}${label}`)
       }
 
@@ -1206,6 +1358,21 @@ export function createOverlayRenderers(state, deps) {
     // 📖 Use scrolling with overlay handler
     const { visible, offset } = sliceOverlayLines(lines, state.changelogScrollOffset, state.terminalRows)
     state.changelogScrollOffset = offset
+
+    // 📖 Mouse support: record changelog layout for click-to-select versions
+    overlayLayout.changelogScrollOffset = offset
+    // 📖 In index phase, version items start at line 4 (header + blank + title + instructions)
+    // 📖 Each version occupies exactly one line. changelogCursorToLine maps cursor → line index.
+    if (state.changelogPhase === 'index') {
+      const map = {}
+      for (let i = 0; i < versionList.length; i++) {
+        map[i] = 4 + i // 📖 3 header-ish lines + 1 blank before version list
+      }
+      overlayLayout.changelogCursorToLine = map
+    } else {
+      overlayLayout.changelogCursorToLine = {}
+    }
+
     const tintedLines = tintOverlayLines(visible, themeColors.overlayBgChangelog, state.terminalCols)
     const cleared = tintedLines.map(l => l + EL)
     return cleared.join('\n')
@@ -1322,8 +1489,10 @@ export function createOverlayRenderers(state, deps) {
     renderRecommend,
     renderFeedback,
     renderChangelog,
+    renderInstalledModels,
     renderIncompatibleFallback,
     startRecommendAnalysis,
     stopRecommendAnalysis,
+    overlayLayout,  // 📖 Mouse support: exposes cursor-to-line maps for click handling
   }
 }