free-coding-models 0.3.17 → 0.3.19

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)
+  })
+}

package/src/tool-launchers.js

@@ -43,6 +43,7 @@ import { getApiKey } from './config.js'
 import { ENV_VAR_NAMES, isWindows } from './provider-metadata.js'
 import { getToolMeta } from './tool-metadata.js'
 import { PROVIDER_METADATA } from './provider-metadata.js'
+import { resolveToolBinaryPath } from './tool-bootstrap.js'
 
 const OPENAI_COMPAT_ENV_KEYS = [
   'OPENAI_API_KEY',
@@ -127,6 +128,10 @@ function applyOpenAiCompatEnv(env, apiKey, baseUrl, modelId) {
   return env
 }
 
+function resolveLaunchCommand(mode, fallbackCommand) {
+  return resolveToolBinaryPath(mode) || fallbackCommand
+}
+
 /**
  * 📖 resolveLauncherModelId returns the provider-native id used by the direct
  * 📖 launchers. Legacy bridge-specific model remapping has been removed.
@@ -562,35 +567,35 @@ export async function startExternalTool(mode, model, config) {
   printConfigArtifacts(meta.label, launchPlan.configArtifacts)
 
   if (mode === 'aider') {
-    return spawnCommand(launchPlan.command, launchPlan.args, launchPlan.env)
+    return spawnCommand(resolveLaunchCommand(mode, launchPlan.command), launchPlan.args, launchPlan.env)
   }
 
   if (mode === 'crush') {
     console.log(chalk.dim('  📖 Crush will use the provider directly for this launch.'))
-    return spawnCommand(launchPlan.command, launchPlan.args, launchPlan.env)
+    return spawnCommand(resolveLaunchCommand(mode, launchPlan.command), launchPlan.args, launchPlan.env)
   }
 
   if (mode === 'goose') {
-    return spawnCommand(launchPlan.command, launchPlan.args, launchPlan.env)
+    return spawnCommand(resolveLaunchCommand(mode, launchPlan.command), launchPlan.args, launchPlan.env)
   }
 
   if (mode === 'qwen') {
-    return spawnCommand(launchPlan.command, launchPlan.args, launchPlan.env)
+    return spawnCommand(resolveLaunchCommand(mode, launchPlan.command), launchPlan.args, launchPlan.env)
   }
 
   if (mode === 'openhands') {
     console.log(chalk.dim(`  📖 OpenHands launched with model: ${model.modelId}`))
-    return spawnCommand(launchPlan.command, launchPlan.args, launchPlan.env)
+    return spawnCommand(resolveLaunchCommand(mode, launchPlan.command), launchPlan.args, launchPlan.env)
   }
 
   if (mode === 'amp') {
     console.log(chalk.dim(`  📖 Amp config updated with model: ${model.modelId}`))
-    return spawnCommand(launchPlan.command, launchPlan.args, launchPlan.env)
+    return spawnCommand(resolveLaunchCommand(mode, launchPlan.command), launchPlan.args, launchPlan.env)
   }
 
   if (mode === 'pi') {
     // 📖 Pi supports --provider and --model flags for guaranteed auto-selection
-    return spawnCommand(launchPlan.command, launchPlan.args, launchPlan.env)
+    return spawnCommand(resolveLaunchCommand(mode, launchPlan.command), launchPlan.args, launchPlan.env)
   }
 
   console.log(chalk.red(`  X Unsupported external tool mode: ${mode}`))

package/src/ui-config.js

@@ -1,49 +1,42 @@
 /**
  * @file ui-config.js
- * @description Central configuration for TUI visual styling.
+ * @description Central configuration helpers for TUI separators and spacing.
  * 
  * @details
- * This module centralizes all visual styling constants for the TUI interface.
- * By keeping colors, separators, and spacing in one place, it becomes easy to
- * customize the look and feel without modifying rendering logic.
+ * This module centralizes the shared table separators used by the TUI. The
+ * theme can change at runtime, so separators must be generated lazily instead
+ * of frozen once at import time.
  * 
  * 📖 Configuration:
- * - BORDER_COLOR: Color of column separators (vertical bars)
- * - BORDER_STYLE: Style of separators (dim, bold, etc.)
- * - HORIZONTAL_SEPARATOR: Character used for horizontal lines
- * - HORIZONTAL_STYLE: Style of horizontal lines
- * - COLUMN_SPACING: Space between columns
+ * - `getVerticalSeparator()` — theme-aware vertical divider
+ * - `getHorizontalLine()` — theme-aware horizontal divider
+ * - `getColumnSpacing()` — formatted spacing wrapper around the divider
  * 
  * @see render-table.js - uses these constants for rendering
  * @see tier-colors.js - for tier-specific color definitions
  */
 
-import chalk from 'chalk';
+import { themeColors } from './theme.js'
 
-// 📖 Column separator (vertical bar) configuration
-export const BORDER_COLOR = chalk.rgb(255, 140, 0); // Gentle dark orange
-export const BORDER_STYLE = 'dim'; // Options: 'dim', 'bold', 'underline', 'inverse', etc.
-export const VERTICAL_SEPARATOR = BORDER_COLOR[BORDER_STYLE]('│');
+// 📖 Column separator stays subtle so it improves scanability without turning
+// 📖 the table into a bright fence.
+export function getVerticalSeparator() {
+  return themeColors.border('│')
+}
 
-// 📖 Horizontal separator configuration
-export const HORIZONTAL_SEPARATOR = '─'; // Unicode horizontal line
-export const HORIZONTAL_STYLE = 'dim'; // Options: 'dim', 'bold', etc.
-export const HORIZONTAL_LINE = chalk[HORIZONTAL_STYLE](HORIZONTAL_SEPARATOR);
+export function getHorizontalLine() {
+  return themeColors.dim('─')
+}
 
-// 📖 Column spacing configuration
-export const COLUMN_SPACING = ` ${VERTICAL_SEPARATOR} `; // Space around vertical separator
+export function getColumnSpacing() {
+  return ` ${getVerticalSeparator()} `
+}
 
-// 📖 Optional: Add more UI styling constants here as needed
-export const TABLE_PADDING = 1; // Padding around table edges
+export const TABLE_PADDING = 1
 
-// 📖 Export all constants for easy import
 export default {
-  BORDER_COLOR,
-  BORDER_STYLE,
-  VERTICAL_SEPARATOR,
-  HORIZONTAL_SEPARATOR,
-  HORIZONTAL_STYLE,
-  HORIZONTAL_LINE,
-  COLUMN_SPACING,
+  getVerticalSeparator,
+  getHorizontalLine,
+  getColumnSpacing,
   TABLE_PADDING
-};
+}