free-coding-models 0.3.16 → 0.3.18

package/src/theme.js

@@ -0,0 +1,315 @@
+/**
+ * @file theme.js
+ * @description Semantic light/dark palette, auto theme detection, and shared TUI colour helpers.
+ *
+ * @functions
+ *   → `detectActiveTheme` — resolve the live theme from user preference or terminal/OS signals
+ *   → `getTheme` — return the currently active resolved theme (`dark` or `light`)
+ *   → `cycleThemeSetting` — rotate persisted theme preference (`auto` → `dark` → `light`)
+ *   → `getThemeStatusLabel` — format the settings/help label for the current theme mode
+ *   → `getProviderRgb` — return the provider accent colour for the active theme
+ *   → `getTierRgb` — return the tier accent colour for the active theme
+ *
+ * @exports { THEME_OPTIONS, detectActiveTheme, getTheme, cycleThemeSetting, getThemeStatusLabel, getReadableTextRgb, getProviderRgb, getTierRgb, themeColors }
+ *
+ * @see src/render-table.js
+ * @see src/overlays.js
+ * @see src/tier-colors.js
+ */
+
+import chalk from 'chalk'
+import { execSync } from 'child_process'
+
+export const THEME_OPTIONS = ['auto', 'dark', 'light']
+
+let activeTheme = 'dark'
+
+const PALETTES = {
+  dark: {
+    text: [234, 239, 248],
+    textStrong: [255, 255, 255],
+    muted: [149, 160, 182],
+    soft: [178, 190, 210],
+    accent: [110, 214, 255],
+    accentStrong: [72, 198, 255],
+    info: [129, 210, 255],
+    success: [112, 231, 181],
+    successStrong: [139, 239, 176],
+    warning: [255, 208, 102],
+    warningStrong: [255, 221, 140],
+    danger: [255, 129, 129],
+    dangerStrong: [255, 166, 166],
+    hotkey: [255, 214, 102],
+    link: [149, 205, 255],
+    border: [111, 125, 149],
+    footerLove: [255, 168, 209],
+    footerCoffee: [255, 209, 134],
+    footerDiscord: [207, 179, 255],
+    overlayFg: [234, 239, 248],
+    overlayBg: {
+      settings: [7, 13, 24],
+      help: [9, 18, 31],
+      recommend: [8, 21, 20],
+      feedback: [31, 13, 20],
+      changelog: [12, 24, 44],
+    },
+    cursor: {
+      defaultBg: [39, 55, 90],
+      defaultFg: [255, 255, 255],
+      installBg: [22, 60, 69],
+      installFg: [255, 255, 255],
+      settingsBg: [26, 54, 34],
+      settingsFg: [255, 255, 255],
+      legacyBg: [67, 31, 69],
+      legacyFg: [255, 255, 255],
+      modelBg: [62, 73, 115],
+      modelFg: [255, 255, 255],
+      recommendedBg: [20, 51, 33],
+      recommendedFg: [234, 239, 248],
+      favoriteBg: [76, 55, 17],
+      favoriteFg: [255, 244, 220],
+    },
+  },
+  light: {
+    text: [28, 36, 51],
+    textStrong: [8, 12, 20],
+    muted: [95, 109, 129],
+    soft: [76, 89, 109],
+    accent: [0, 120, 186],
+    accentStrong: [0, 99, 163],
+    info: [0, 109, 168],
+    success: [0, 118, 68],
+    successStrong: [0, 96, 56],
+    warning: [146, 90, 0],
+    warningStrong: [171, 102, 0],
+    danger: [177, 53, 53],
+    dangerStrong: [147, 35, 48],
+    hotkey: [171, 98, 0],
+    link: [0, 94, 170],
+    border: [151, 166, 188],
+    footerLove: [176, 79, 128],
+    footerCoffee: [170, 102, 0],
+    footerDiscord: [104, 83, 190],
+    overlayFg: [28, 36, 51],
+    overlayBg: {
+      settings: [248, 250, 255],
+      help: [246, 250, 255],
+      recommend: [246, 252, 248],
+      feedback: [255, 247, 248],
+      changelog: [244, 248, 255],
+    },
+    cursor: {
+      defaultBg: [217, 231, 255],
+      defaultFg: [9, 18, 35],
+      installBg: [218, 242, 236],
+      installFg: [12, 33, 26],
+      settingsBg: [225, 244, 229],
+      settingsFg: [14, 43, 27],
+      legacyBg: [248, 228, 244],
+      legacyFg: [76, 28, 73],
+      modelBg: [209, 223, 255],
+      modelFg: [9, 18, 35],
+      recommendedBg: [221, 245, 229],
+      recommendedFg: [17, 47, 28],
+      favoriteBg: [255, 241, 208],
+      favoriteFg: [79, 53, 0],
+    },
+  },
+}
+
+const PROVIDER_PALETTES = {
+  dark: {
+    nvidia: [132, 235, 168],
+    groq: [255, 191, 144],
+    cerebras: [153, 215, 255],
+    sambanova: [255, 215, 142],
+    openrouter: [228, 191, 239],
+    huggingface: [255, 235, 122],
+    replicate: [166, 212, 255],
+    deepinfra: [146, 222, 213],
+    fireworks: [255, 184, 194],
+    codestral: [245, 175, 212],
+    hyperbolic: [255, 160, 127],
+    scaleway: [115, 209, 255],
+    googleai: [166, 210, 255],
+    siliconflow: [145, 232, 243],
+    together: [255, 232, 98],
+    cloudflare: [255, 191, 118],
+    perplexity: [243, 157, 195],
+    qwen: [255, 213, 128],
+    zai: [150, 208, 255],
+    iflow: [211, 229, 101],
+  },
+  light: {
+    nvidia: [0, 126, 73],
+    groq: [171, 86, 22],
+    cerebras: [0, 102, 177],
+    sambanova: [165, 94, 0],
+    openrouter: [122, 65, 156],
+    huggingface: [135, 104, 0],
+    replicate: [0, 94, 163],
+    deepinfra: [0, 122, 117],
+    fireworks: [183, 55, 72],
+    codestral: [157, 61, 110],
+    hyperbolic: [178, 68, 27],
+    scaleway: [0, 113, 189],
+    googleai: [0, 111, 168],
+    siliconflow: [0, 115, 138],
+    together: [122, 101, 0],
+    cloudflare: [176, 92, 0],
+    perplexity: [171, 62, 121],
+    qwen: [132, 89, 0],
+    zai: [0, 104, 171],
+    iflow: [107, 130, 0],
+  },
+}
+
+const TIER_PALETTES = {
+  dark: {
+    'S+': [111, 255, 164],
+    'S': [147, 241, 101],
+    'A+': [201, 233, 104],
+    'A': [255, 211, 101],
+    'A-': [255, 178, 100],
+    'B+': [255, 145, 112],
+    'B': [255, 113, 113],
+    'C': [255, 139, 164],
+  },
+  light: {
+    'S+': [0, 122, 58],
+    'S': [54, 122, 0],
+    'A+': [95, 113, 0],
+    'A': [128, 92, 0],
+    'A-': [156, 80, 0],
+    'B+': [171, 69, 0],
+    'B': [168, 44, 44],
+    'C': [123, 35, 75],
+  },
+}
+
+function currentPalette() {
+  return PALETTES[activeTheme] ?? PALETTES.dark
+}
+
+function themeLabel(theme) {
+  return theme.charAt(0).toUpperCase() + theme.slice(1)
+}
+
+function buildStyle({ fgRgb = null, bgRgb = null, bold = false, italic = false } = {}) {
+  let style = chalk
+  if (bgRgb) style = style.bgRgb(...bgRgb)
+  if (fgRgb) style = style.rgb(...fgRgb)
+  if (bold) style = style.bold
+  if (italic) style = style.italic
+  return style
+}
+
+export function getReadableTextRgb(bgRgb) {
+  const [r, g, b] = bgRgb
+  const yiq = (r * 299 + g * 587 + b * 114) / 1000
+  return yiq >= 150 ? [10, 16, 28] : [248, 251, 255]
+}
+
+export function detectActiveTheme(configTheme = 'auto') {
+  if (configTheme === 'dark' || configTheme === 'light') {
+    activeTheme = configTheme
+    return activeTheme
+  }
+
+  const fgbg = process.env.COLORFGBG || ''
+  if (fgbg.includes(';15') || fgbg.includes(';7') || fgbg.includes(';base03')) {
+    activeTheme = 'light'
+    return activeTheme
+  }
+  if (fgbg) {
+    activeTheme = 'dark'
+    return activeTheme
+  }
+
+  if (process.platform === 'darwin') {
+    try {
+      const style = execSync('defaults read -g AppleInterfaceStyle 2>/dev/null', { timeout: 100 }).toString().trim()
+      activeTheme = style === 'Dark' ? 'dark' : 'light'
+    } catch {
+      activeTheme = 'light'
+    }
+    return activeTheme
+  }
+
+  activeTheme = 'dark'
+  return activeTheme
+}
+
+export function getTheme() {
+  return activeTheme
+}
+
+export function cycleThemeSetting(currentTheme = 'auto') {
+  const currentIdx = THEME_OPTIONS.indexOf(currentTheme)
+  const nextIdx = currentIdx === -1 ? 0 : (currentIdx + 1) % THEME_OPTIONS.length
+  return THEME_OPTIONS[nextIdx]
+}
+
+export function getThemeStatusLabel(setting = 'auto') {
+  if (setting === 'auto') return `Auto → ${themeLabel(activeTheme)}`
+  return themeLabel(setting)
+}
+
+export function getProviderRgb(providerKey) {
+  const palette = PROVIDER_PALETTES[activeTheme] ?? PROVIDER_PALETTES.dark
+  return palette[providerKey] ?? currentPalette().accent
+}
+
+export function getTierRgb(tier) {
+  const palette = TIER_PALETTES[activeTheme] ?? TIER_PALETTES.dark
+  return palette[tier] ?? currentPalette().textStrong
+}
+
+function paintRgb(rgb, text, options = {}) {
+  return buildStyle({ fgRgb: rgb, ...options })(text)
+}
+
+function paintBg(bgRgb, text, fgRgb = null, options = {}) {
+  return buildStyle({ bgRgb, fgRgb: fgRgb ?? getReadableTextRgb(bgRgb), ...options })(text)
+}
+
+export const themeColors = {
+  text: (text) => paintRgb(currentPalette().text, text),
+  textBold: (text) => paintRgb(currentPalette().textStrong, text, { bold: true }),
+  dim: (text) => paintRgb(currentPalette().muted, text),
+  soft: (text) => paintRgb(currentPalette().soft, text),
+  accent: (text) => paintRgb(currentPalette().accent, text),
+  accentBold: (text) => paintRgb(currentPalette().accentStrong, text, { bold: true }),
+  info: (text) => paintRgb(currentPalette().info, text),
+  success: (text) => paintRgb(currentPalette().success, text),
+  successBold: (text) => paintRgb(currentPalette().successStrong, text, { bold: true }),
+  warning: (text) => paintRgb(currentPalette().warning, text),
+  warningBold: (text) => paintRgb(currentPalette().warningStrong, text, { bold: true }),
+  error: (text) => paintRgb(currentPalette().danger, text),
+  errorBold: (text) => paintRgb(currentPalette().dangerStrong, text, { bold: true }),
+  hotkey: (text) => paintRgb(currentPalette().hotkey, text, { bold: true }),
+  link: (text) => paintRgb(currentPalette().link, text),
+  border: (text) => paintRgb(currentPalette().border, text),
+  footerLove: (text) => paintRgb(currentPalette().footerLove, text),
+  footerCoffee: (text) => paintRgb(currentPalette().footerCoffee, text),
+  footerDiscord: (text) => paintRgb(currentPalette().footerDiscord, text),
+  metricGood: (text) => paintRgb(currentPalette().successStrong, text),
+  metricOk: (text) => paintRgb(currentPalette().info, text),
+  metricWarn: (text) => paintRgb(currentPalette().warning, text),
+  metricBad: (text) => paintRgb(currentPalette().danger, text),
+  provider: (providerKey, text, { bold = false } = {}) => paintRgb(getProviderRgb(providerKey), text, { bold }),
+  tier: (tier, text, { bold = true } = {}) => paintRgb(getTierRgb(tier), text, { bold }),
+  badge: (text, bgRgb, fgRgb = null) => paintBg(bgRgb, ` ${text} `, fgRgb, { bold: true }),
+  bgCursor: (text) => paintBg(currentPalette().cursor.defaultBg, text, currentPalette().cursor.defaultFg),
+  bgCursorInstall: (text) => paintBg(currentPalette().cursor.installBg, text, currentPalette().cursor.installFg),
+  bgCursorSettingsList: (text) => paintBg(currentPalette().cursor.settingsBg, text, currentPalette().cursor.settingsFg),
+  bgCursorLegacy: (text) => paintBg(currentPalette().cursor.legacyBg, text, currentPalette().cursor.legacyFg),
+  bgModelCursor: (text) => paintBg(currentPalette().cursor.modelBg, text, currentPalette().cursor.modelFg),
+  bgModelRecommended: (text) => paintBg(currentPalette().cursor.recommendedBg, text, currentPalette().cursor.recommendedFg),
+  bgModelFavorite: (text) => paintBg(currentPalette().cursor.favoriteBg, text, currentPalette().cursor.favoriteFg),
+  overlayBgSettings: (text) => paintBg(currentPalette().overlayBg.settings, text, currentPalette().overlayFg),
+  overlayBgHelp: (text) => paintBg(currentPalette().overlayBg.help, text, currentPalette().overlayFg),
+  overlayBgRecommend: (text) => paintBg(currentPalette().overlayBg.recommend, text, currentPalette().overlayFg),
+  overlayBgFeedback: (text) => paintBg(currentPalette().overlayBg.feedback, text, currentPalette().overlayFg),
+  overlayBgChangelog: (text) => paintBg(currentPalette().overlayBg.changelog, text, currentPalette().overlayFg),
+}

package/src/tier-colors.js

@@ -1,6 +1,6 @@
 /**
  * @file tier-colors.js
- * @description Chalk colour functions for each tier level, extracted from bin/free-coding-models.js.
+ * @description Theme-aware Chalk colour functions for each tier level.
  *
  * @details
  *   The tier system maps model quality tiers (S+, S, A+, A, A-, B+, B, C) to a
@@ -9,9 +9,10 @@
  *   single, consistent visual language without depending on the whole TUI entry point.
  *
  *   The gradient is deliberately designed so that the higher the tier the more
- *   "neon" and attention-grabbing the colour, while lower tiers fade toward dark red.
- *   `chalk.rgb()` is used for fine-grained control — terminal 256-colour and truecolour
- *   modes both support this; on terminals that don't, chalk gracefully degrades.
+ *   The previous palette used very dark reds and bright yellows directly, which
+ *   became muddy on dark terminals and nearly invisible on light ones. This
+ *   module now delegates to the semantic theme palette so tier colours stay
+ *   readable in both modes while keeping the same best→worst ordering.
  *
  * @exports
  *   TIER_COLOR — object mapping tier string → chalk colouring function
@@ -21,17 +22,14 @@
  */
 
 import chalk from 'chalk'
+import { getTierRgb } from './theme.js'
 
-// 📖 Tier colors: green gradient (best) → yellow → orange → red (worst).
-// 📖 Uses chalk.rgb() for fine-grained color control across 8 tier levels.
-// 📖 Each entry is a function (t) => styled string so it can be applied to any text.
-export const TIER_COLOR = {
-  'S+': t => chalk.bold.rgb(0,   255,  80)(t),   // 🟢 bright neon green  — elite
-  'S':  t => chalk.bold.rgb(80,  220,   0)(t),   // 🟢 green              — excellent
-  'A+': t => chalk.bold.rgb(170, 210,   0)(t),   // 🟡 yellow-green       — great
-  'A':  t => chalk.bold.rgb(240, 190,   0)(t),   // 🟡 yellow             — good
-  'A-': t => chalk.bold.rgb(255, 130,   0)(t),   // 🟠 amber              — decent
-  'B+': t => chalk.bold.rgb(255,  70,   0)(t),   // 🟠 orange-red         — average
-  'B':  t => chalk.bold.rgb(210,  20,   0)(t),   // 🔴 red                — below avg
-  'C':  t => chalk.bold.rgb(140,   0,   0)(t),   // 🔴 dark red           — lightweight
-}
+// 📖 TIER_COLOR remains object-like for existing call sites, but every access is
+// 📖 resolved lazily from the live theme so `G`/Settings theme switches repaint
+// 📖 the whole TUI without rebuilding import-time constants.
+export const TIER_COLOR = new Proxy({}, {
+  get(_target, tier) {
+    if (typeof tier !== 'string') return undefined
+    return (text) => chalk.bold.rgb(...getTierRgb(tier))(text)
+  },
+})

package/src/tool-bootstrap.js

@@ -0,0 +1,310 @@
+/**
+ * @file src/tool-bootstrap.js
+ * @description Shared detection and auto-install helpers for external coding tools launched by FCM.
+ *
+ * @details
+ *   📖 This module answers three operational questions for every supported launcher:
+ *   - which executable should exist locally before FCM can launch the tool
+ *   - how to detect that executable without spawning the full TUI/CLI itself
+ *   - which official install command FCM can offer when the tool is missing
+ *
+ *   📖 The goal is deliberately narrow. We only solve the "binary missing" bootstrap
+ *   path so the main TUI can keep the user's selected model, offer a tiny Yes/No
+ *   confirmation overlay, then continue with the existing config-write + launch flow.
+ *
+ *   📖 FCM prefers npm when a tool officially supports it because the binary usually
+ *   lands in a predictable global location and works immediately in the same session.
+ *   For tools that do not have a maintained npm install path, we use the official
+ *   installer script documented by the tool itself.
+ *
+ * @functions
+ *   → `getToolBootstrapMeta` — static metadata for one tool mode
+ *   → `resolveToolBinaryPath` — find a launcher executable in PATH or common user bin dirs
+ *   → `isToolInstalled` — quick boolean wrapper around binary resolution
+ *   → `getToolInstallPlan` — pick the platform-specific install command for a tool
+ *   → `installToolWithPlan` — execute the chosen install command with inherited stdio
+ *
+ * @exports
+ *   TOOL_BOOTSTRAP_METADATA, getToolBootstrapMeta, resolveToolBinaryPath,
+ *   isToolInstalled, getToolInstallPlan, installToolWithPlan
+ *
+ * @see src/key-handler.js
+ * @see src/tool-launchers.js
+ * @see src/opencode.js
+ */
+
+import { spawn } from 'child_process'
+import { existsSync, statSync } from 'fs'
+import { homedir } from 'os'
+import { delimiter, extname, join } from 'path'
+import { isWindows } from './provider-metadata.js'
+
+const HOME = homedir()
+
+// 📖 Common user-level binary directories that installer scripts frequently use.
+// 📖 We search them in addition to PATH so FCM can keep going right after install
+// 📖 even if the user's shell profile has not been reloaded yet.
+const COMMON_USER_BIN_DIRS = isWindows
+  ? [
+      join(HOME, '.local', 'bin'),
+      join(HOME, 'AppData', 'Roaming', 'npm'),
+      join(HOME, 'scoop', 'shims'),
+    ]
+  : [
+      join(HOME, '.local', 'bin'),
+      join(HOME, '.bun', 'bin'),
+      join(HOME, '.npm-global', 'bin'),
+    ]
+
+function uniqueStrings(values = []) {
+  return [...new Set(values.filter((value) => typeof value === 'string' && value.trim()))]
+}
+
+function pathEntries(env = process.env) {
+  return uniqueStrings([
+    ...(String(env.PATH || '').split(delimiter)),
+    ...(env.npm_config_prefix ? [isWindows ? env.npm_config_prefix : join(env.npm_config_prefix, 'bin')] : []),
+    ...COMMON_USER_BIN_DIRS,
+  ])
+}
+
+function executableSuffixes(env = process.env) {
+  if (!isWindows) return ['']
+  const raw = String(env.PATHEXT || '.EXE;.CMD;.BAT;.COM')
+  return uniqueStrings(raw.split(';').flatMap((ext) => {
+    const normalized = ext.trim()
+    if (!normalized) return []
+    return [normalized.toLowerCase(), normalized.toUpperCase()]
+  }))
+}
+
+function isRunnableFile(filePath) {
+  try {
+    return existsSync(filePath) && statSync(filePath).isFile()
+  } catch {
+    return false
+  }
+}
+
+function resolveBinaryPath(binaryName, env = process.env) {
+  if (!binaryName || typeof binaryName !== 'string') return null
+
+  const entries = pathEntries(env)
+  if (entries.length === 0) return null
+
+  const hasExtension = extname(binaryName).length > 0
+  const suffixes = isWindows
+    ? (hasExtension ? [''] : executableSuffixes(env))
+    : ['']
+
+  for (const dir of entries) {
+    for (const suffix of suffixes) {
+      const candidate = join(dir, `${binaryName}${suffix}`)
+      if (isRunnableFile(candidate)) return candidate
+    }
+  }
+
+  return null
+}
+
+export const TOOL_BOOTSTRAP_METADATA = {
+  opencode: {
+    binary: 'opencode',
+    docsUrl: 'https://opencode.ai/download',
+    install: {
+      default: {
+        shellCommand: 'npm install -g opencode-ai',
+        summary: 'Install OpenCode CLI globally via npm.',
+      },
+    },
+  },
+  'opencode-desktop': {
+    binary: null,
+    docsUrl: 'https://opencode.ai/download',
+    installUnsupported: {
+      default: 'OpenCode Desktop uses platform-specific app installers, so FCM does not auto-install it yet.',
+    },
+  },
+  openclaw: {
+    binary: 'openclaw',
+    docsUrl: 'https://docs.openclaw.ai/install',
+    install: {
+      default: {
+        shellCommand: 'npm install -g openclaw@latest',
+        summary: 'Install OpenClaw globally via npm.',
+      },
+    },
+  },
+  crush: {
+    binary: 'crush',
+    docsUrl: 'https://github.com/charmbracelet/crush',
+    install: {
+      default: {
+        shellCommand: 'npm install -g @charmland/crush',
+        summary: 'Install Crush globally via npm.',
+      },
+    },
+  },
+  goose: {
+    binary: 'goose',
+    docsUrl: 'https://block.github.io/goose/docs/getting-started/installation/',
+    install: {
+      default: {
+        shellCommand: 'curl -fsSL https://github.com/block/goose/releases/download/stable/download_cli.sh | CONFIGURE=false bash',
+        summary: 'Install goose CLI with the official installer script.',
+      },
+      win32: {
+        shellCommand: 'powershell -NoProfile -ExecutionPolicy Bypass -Command "Invoke-WebRequest -Uri https://raw.githubusercontent.com/block/goose/main/download_cli.ps1 -OutFile $env:TEMP\\download_cli.ps1; & $env:TEMP\\download_cli.ps1"',
+        summary: 'Install goose CLI with the official PowerShell installer.',
+      },
+    },
+  },
+  aider: {
+    binary: 'aider',
+    docsUrl: 'https://aider.chat/docs/install.html',
+    install: {
+      default: {
+        shellCommand: 'curl -LsSf https://aider.chat/install.sh | sh',
+        summary: 'Install aider with the official installer.',
+      },
+      win32: {
+        shellCommand: 'powershell -ExecutionPolicy ByPass -c "irm https://aider.chat/install.ps1 | iex"',
+        summary: 'Install aider with the official PowerShell installer.',
+      },
+    },
+  },
+  qwen: {
+    binary: 'qwen',
+    docsUrl: 'https://qwenlm.github.io/qwen-code-docs/en/users/quickstart/',
+    install: {
+      default: {
+        shellCommand: 'npm install -g @qwen-code/qwen-code@latest',
+        summary: 'Install Qwen Code globally via npm.',
+      },
+    },
+  },
+  openhands: {
+    binary: 'openhands',
+    docsUrl: 'https://docs.openhands.dev/openhands/usage/cli/installation',
+    install: {
+      default: {
+        shellCommand: 'curl -fsSL https://install.openhands.dev/install.sh | sh',
+        summary: 'Install OpenHands CLI with the official installer.',
+      },
+    },
+    installUnsupported: {
+      win32: 'OpenHands CLI currently recommends installation inside WSL on Windows.',
+    },
+  },
+  amp: {
+    binary: 'amp',
+    docsUrl: 'https://ampcode.com/manual',
+    install: {
+      default: {
+        shellCommand: 'npm install -g @sourcegraph/amp',
+        summary: 'Install Amp globally via npm.',
+        note: 'Amp documents npm as a fallback install path. Its plugin API works best with the binary installer from ampcode.com/install.',
+      },
+    },
+  },
+  pi: {
+    binary: 'pi',
+    docsUrl: 'https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/README.md',
+    install: {
+      default: {
+        shellCommand: 'npm install -g @mariozechner/pi-coding-agent',
+        summary: 'Install Pi Coding Agent globally via npm.',
+      },
+    },
+  },
+}
+
+export function getToolBootstrapMeta(mode) {
+  return TOOL_BOOTSTRAP_METADATA[mode] || null
+}
+
+export function resolveToolBinaryPath(mode, options = {}) {
+  const meta = getToolBootstrapMeta(mode)
+  if (!meta?.binary) return null
+  return resolveBinaryPath(meta.binary, options.env || process.env)
+}
+
+export function isToolInstalled(mode, options = {}) {
+  return Boolean(resolveToolBinaryPath(mode, options))
+}
+
+export function getToolInstallPlan(mode, options = {}) {
+  const meta = getToolBootstrapMeta(mode)
+  const platform = options.platform || process.platform
+
+  if (!meta) {
+    return {
+      supported: false,
+      mode,
+      binary: null,
+      docsUrl: null,
+      reason: `Unknown tool mode: ${mode}`,
+    }
+  }
+
+  const platformUnsupportedReason = meta.installUnsupported?.[platform]
+  if (platformUnsupportedReason) {
+    return {
+      supported: false,
+      mode,
+      binary: meta.binary || null,
+      docsUrl: meta.docsUrl || null,
+      reason: platformUnsupportedReason,
+    }
+  }
+
+  const installPlan = meta.install?.[platform] || meta.install?.default || null
+  if (!installPlan) {
+    return {
+      supported: false,
+      mode,
+      binary: meta.binary || null,
+      docsUrl: meta.docsUrl || null,
+      reason: meta.installUnsupported?.default || 'No auto-install plan is available for this tool on the current platform.',
+    }
+  }
+
+  return {
+    supported: true,
+    mode,
+    binary: meta.binary || null,
+    docsUrl: meta.docsUrl || null,
+    shellCommand: installPlan.shellCommand,
+    summary: installPlan.summary,
+    note: installPlan.note || null,
+  }
+}
+
+export function installToolWithPlan(plan, options = {}) {
+  return new Promise((resolve, reject) => {
+    if (!plan?.supported || !plan.shellCommand) {
+      resolve({
+        ok: false,
+        exitCode: 1,
+        command: plan?.shellCommand || null,
+      })
+      return
+    }
+
+    const child = spawn(plan.shellCommand, [], {
+      stdio: 'inherit',
+      shell: true,
+      env: { ...process.env, ...(options.env || {}) },
+      cwd: options.cwd || process.cwd(),
+    })
+
+    child.on('exit', (code) => {
+      resolve({
+        ok: code === 0,
+        exitCode: typeof code === 'number' ? code : 1,
+        command: plan.shellCommand,
+      })
+    })
+    child.on('error', reject)
+  })
+}