Function resolvePythonExecutable

packages/runtime-core/src/python-env.ts:23–86

(pythonPath: string)

 * @throws Error if the path doesn't exist or no Python executable is found
 */
export async function resolvePythonExecutable(pythonPath: string): Promise<string> {
  if (isBareSystemPython(pythonPath)) {
    return pythonPath
  }

  let fileStat: Awaited<ReturnType<typeof stat>>
  try {
    fileStat = await stat(pythonPath)
  } catch (err) {
    const error = err as NodeJS.ErrnoException
    if (error.code === 'ENOENT') {
      throw new Error(`Python path not found: ${pythonPath}`)
    }
    throw new Error(`Failed to access Python path: ${pythonPath} (${error.code}: ${error.message})`)
  }

  // Case 1: Direct path to Python executable
  if (fileStat.isFile()) {
    const name = basename(pythonPath).toLowerCase()
    if (name.startsWith('python')) {
      return pythonPath
    }
    throw new Error(
      `Path is a file but doesn't appear to be a Python executable: ${pythonPath}\n` +
        'Expected a file named python, python3, python.exe, or similar.'
    )
  }

  if (!fileStat.isDirectory()) {
    throw new Error(`Python path is neither a file nor a directory: ${pythonPath}`)
  }

  // Case 2: Directory containing python directly (bin/ or Scripts/ folder)
  const directPython = await findPythonInDirectory(pythonPath, PYTHON_EXECUTABLES)
  if (directPython) {
    return directPython
  }

  // Case 3: Venv root directory (look in bin/ or Scripts/)
  const binDir = join(pythonPath, VENV_BIN_DIR)
  const binDirStat = await stat(binDir).catch(() => null)

  if (binDirStat?.isDirectory()) {
    const venvPython = await findPythonInDirectory(binDir, PYTHON_EXECUTABLES)
    if (venvPython) {
      return venvPython
    }
  }

  // No Python found - provide helpful error message
  const searchedPaths = [
    ...PYTHON_EXECUTABLES.map(c => join(pythonPath, c)),
    ...PYTHON_EXECUTABLES.map(c => join(binDir, c)),
  ]

  throw new Error(
    `No Python executable found at: ${pythonPath}\n\n` +
      `Searched for:\n${searchedPaths.map(p => `  - ${p}`).join('\n')}\n\n` +