nodepyx 1.0.0

package/src/env/PythonDetector.ts

@@ -0,0 +1,414 @@
+/**
+ * nodepyx — PythonDetector
+ * Locates a usable Python interpreter on the host system.
+ *
+ * Detection order:
+ *   1. nodepyx_PYTHON environment variable
+ *   2. Explicit pythonPath from nodepyxConfig
+ *   3. Virtualenv / Conda path from config
+ *   4. python3 / python3.x on PATH
+ *   5. python on PATH
+ *   6. Common installation locations (Windows/macOS/Linux)
+ *
+ * Validates:
+ *   - Python version ≥ 3.8
+ *   - Not a stub (pyenv shim without real installation)
+ *   - Has required modules available (when requested)
+ */
+
+import { execSync, spawnSync } from 'child_process';
+import * as fs   from 'fs';
+import * as path from 'path';
+import { Logger } from '../utils/Logger';
+
+const logger = new Logger('PythonDetector');
+
+// ─── Types ─────────────────────────────────────────────────────────────────
+
+export interface PythonInfo {
+  /** Absolute path to Python executable */
+  executable: string;
+  /** Python version string (e.g. '3.11.4') */
+  version: string;
+  /** Major.minor as numbers */
+  major: number;
+  minor: number;
+  patch: number;
+  /** Absolute path to Python prefix (sys.prefix) */
+  prefix: string;
+  /** Whether this is inside a virtualenv */
+  isVirtualenv: boolean;
+  /** Whether this is inside a Conda environment */
+  isConda: boolean;
+  /** conda environment name (if applicable) */
+  condaEnv?: string;
+  /** Platform: 'linux' | 'darwin' | 'win32' */
+  platform: string;
+  /** Architecture: 'x64' | 'arm64' */
+  arch: string;
+}
+
+export interface DetectorOptions {
+  /** Minimum Python version required. Default: [3, 8] */
+  minVersion?: [number, number];
+  /** Explicit path to check first */
+  pythonPath?: string;
+  /** Timeout for subprocess calls (ms). Default: 10000 */
+  timeout?: number;
+  /** Skip PATH scanning and only check explicit path. Default: false */
+  explicitOnly?: boolean;
+  /** Modules that must be importable. Default: [] */
+  requiredModules?: string[];
+}
+
+// ─── Platform-specific common locations ─────────────────────────────────────
+
+const COMMON_LOCATIONS: Readonly<Record<NodeJS.Platform, string[]>> = {
+  linux:   [
+    '/usr/bin/python3',
+    '/usr/local/bin/python3',
+    '/opt/conda/bin/python3',
+    '/usr/bin/python3.12',
+    '/usr/bin/python3.11',
+    '/usr/bin/python3.10',
+    '/usr/bin/python3.9',
+    '/usr/bin/python3.8',
+    '/usr/bin/python',
+  ],
+  darwin:  [
+    '/usr/local/bin/python3',
+    '/opt/homebrew/bin/python3',
+    '/opt/homebrew/bin/python3.12',
+    '/opt/homebrew/bin/python3.11',
+    '/opt/homebrew/bin/python3.10',
+    '/Library/Frameworks/Python.framework/Versions/3.12/bin/python3',
+    '/Library/Frameworks/Python.framework/Versions/3.11/bin/python3',
+    '/Library/Frameworks/Python.framework/Versions/3.10/bin/python3',
+    '/usr/bin/python3',
+    '/usr/bin/python',
+  ],
+  win32:   [
+    'C:\\Python312\\python.exe',
+    'C:\\Python311\\python.exe',
+    'C:\\Python310\\python.exe',
+    'C:\\Python39\\python.exe',
+    'C:\\Python38\\python.exe',
+    `${process.env.LOCALAPPDATA}\\Programs\\Python\\Python312\\python.exe`,
+    `${process.env.LOCALAPPDATA}\\Programs\\Python\\Python311\\python.exe`,
+    `${process.env.LOCALAPPDATA}\\Programs\\Python\\Python310\\python.exe`,
+    `${process.env.APPDATA}\\Python\\Python312\\python.exe`,
+  ],
+  aix:     [],
+  android: [],
+  cygwin:  [],
+  freebsd: [],
+  haiku:   [],
+  netbsd:  [],
+  openbsd: [],
+  sunos:   [],
+} as const;
+
+// Python info extraction script
+const PROBE_SCRIPT = `
+import sys, os, json
+prefix = sys.prefix
+is_venv = (
+    hasattr(sys, 'real_prefix') or
+    (hasattr(sys, 'base_prefix') and sys.base_prefix != sys.prefix)
+)
+is_conda = 'conda' in sys.version or os.path.exists(os.path.join(prefix, 'conda-meta'))
+conda_env = os.environ.get('CONDA_DEFAULT_ENV')
+info = {
+    'version': '.'.join(map(str, sys.version_info[:3])),
+    'major':   sys.version_info.major,
+    'minor':   sys.version_info.minor,
+    'patch':   sys.version_info.micro,
+    'prefix':  prefix,
+    'is_venv': is_venv,
+    'is_conda': is_conda,
+    'conda_env': conda_env,
+    'platform': sys.platform,
+    'arch': __import__('platform').machine(),
+}
+print(json.dumps(info))
+`.trim();
+
+/**
+ * PythonDetector — locates a usable Python interpreter.
+ *
+ * @example
+ * ```typescript
+ * const detector = new PythonDetector({ minVersion: [3, 9] });
+ * const info = await detector.detect();
+ * console.log(info.executable);  // /usr/bin/python3
+ * console.log(info.version);     // 3.11.4
+ * ```
+ */
+export class PythonDetector {
+  private readonly _opts: Required<DetectorOptions>;
+
+  constructor(options: DetectorOptions = {}) {
+    this._opts = {
+      minVersion:      options.minVersion      ?? [3, 8],
+      pythonPath:      options.pythonPath       ?? '',
+      timeout:         options.timeout          ?? 10_000,
+      explicitOnly:    options.explicitOnly      ?? false,
+      requiredModules: options.requiredModules   ?? [],
+    };
+  }
+
+  // ─── Public API ──────────────────────────────────────────────────────────
+
+  /**
+   * Detect and validate a Python interpreter.
+   * Returns the first suitable interpreter found.
+   * Throws if no suitable interpreter is found.
+   */
+  async detect(): Promise<PythonInfo> {
+    const candidates = this._buildCandidates();
+
+    for (const candidate of candidates) {
+      const info = this._probe(candidate);
+      if (!info) {continue;}
+
+      if (!this._meetsVersionRequirement(info)) {
+        logger.debug(`PythonDetector: ${candidate} — version ${info.version} < ${this._opts.minVersion.join('.')}`);
+        continue;
+      }
+
+      if (this._opts.requiredModules.length > 0) {
+        const missing = this._checkModules(info.executable, this._opts.requiredModules);
+        if (missing.length > 0) {
+          logger.debug(`PythonDetector: ${candidate} — missing modules: ${missing.join(', ')}`);
+          continue;
+        }
+      }
+
+      logger.info(`PythonDetector: using ${info.executable} (${info.version})`);
+      return info;
+    }
+
+    throw new PythonNotFoundError(
+      `Could not find a suitable Python interpreter (>= ${this._opts.minVersion.join('.')}).` +
+      '\nSolutions:' +
+      '\n  1. Install Python 3.8+: https://python.org' +
+      '\n  2. Set nodepyx_PYTHON env var to the Python executable path' +
+      '\n  3. Pass pythonPath in the nodepyx config' +
+      '\n  4. Create a virtualenv: nodepyx.init({ virtualenv: { path: ".venv", packages: [] } })',
+    );
+  }
+
+  /**
+   * Probe a specific Python executable and return its info.
+   * Returns null if the executable is invalid or doesn't exist.
+   */
+  probe(executablePath: string): PythonInfo | null {
+    return this._probe(executablePath);
+  }
+
+  /**
+   * Check if a Python executable meets the minimum version requirement.
+   */
+  isCompatible(info: PythonInfo): boolean {
+    return this._meetsVersionRequirement(info);
+  }
+
+  /**
+   * Check which required modules are missing for a given Python.
+   * Returns an empty array if all modules are available.
+   */
+  checkModules(executable: string, modules: string[]): string[] {
+    return this._checkModules(executable, modules);
+  }
+
+  /**
+   * List all Python executables found in common locations and PATH.
+   */
+  async listAll(): Promise<PythonInfo[]> {
+    const results: PythonInfo[] = [];
+    const candidates = this._buildCandidates();
+
+    for (const candidate of candidates) {
+      const info = this._probe(candidate);
+      if (info) {results.push(info);}
+    }
+
+    return results;
+  }
+
+  // ─── Private ─────────────────────────────────────────────────────────────
+
+  private _buildCandidates(): string[] {
+    const candidates: string[] = [];
+
+    // 1. nodepyx_PYTHON env var (highest priority)
+    if (process.env.nodepyx_PYTHON) {
+      candidates.push(process.env.nodepyx_PYTHON);
+    }
+
+    // 2. Explicit config path
+    if (this._opts.pythonPath) {
+      candidates.push(this._opts.pythonPath);
+      // Also try bin/python inside a venv/conda root
+      const binDir = process.platform === 'win32' ? 'Scripts' : 'bin';
+      candidates.push(path.join(this._opts.pythonPath, binDir, 'python3'));
+      candidates.push(path.join(this._opts.pythonPath, binDir, 'python'));
+    }
+
+    if (this._opts.explicitOnly) {return candidates;}
+
+    // 3. PATH candidates
+    const pathCandidates = [
+      'python3.12', 'python3.11', 'python3.10', 'python3.9', 'python3.8',
+      'python3', 'python',
+    ];
+    for (const name of pathCandidates) {
+      const found = this._which(name);
+      if (found) {candidates.push(found);}
+    }
+
+    // 4. Common installation locations
+    const platformKey = process.platform as NodeJS.Platform;
+    for (const loc of COMMON_LOCATIONS[platformKey] ?? []) {
+      if (loc) {candidates.push(loc);}
+    }
+
+    // Deduplicate while preserving order
+    return [...new Set(candidates)];
+  }
+
+  private _probe(executable: string): PythonInfo | null {
+    if (!executable) {return null;}
+
+    try {
+      // Resolve Windows executable extension
+      const exec = this._resolveExecutable(executable);
+      if (!exec) {return null;}
+
+      const result = spawnSync(exec, ['-c', PROBE_SCRIPT], {
+        encoding:   'utf8',
+        timeout:    this._opts.timeout,
+        maxBuffer:  1024 * 1024,
+        env:        { ...process.env, PYTHONDONTWRITEBYTECODE: '1' },
+      });
+
+      if (result.status !== 0 || result.error || !result.stdout.trim()) {
+        return null;
+      }
+
+      const raw = JSON.parse(result.stdout.trim()) as {
+        version:   string;
+        major:     number;
+        minor:     number;
+        patch:     number;
+        prefix:    string;
+        is_venv:   boolean;
+        is_conda:  boolean;
+        conda_env: string | null;
+        platform:  string;
+        arch:      string;
+      };
+
+      return {
+        executable:   exec,
+        version:      raw.version,
+        major:        raw.major,
+        minor:        raw.minor,
+        patch:        raw.patch,
+        prefix:       raw.prefix,
+        isVirtualenv: raw.is_venv,
+        isConda:      raw.is_conda,
+        condaEnv:     raw.conda_env ?? undefined,
+        platform:     raw.platform,
+        arch:         raw.arch,
+      };
+    } catch (err) {
+      logger.debug(`PythonDetector._probe(${executable}) failed`, err);
+      return null;
+    }
+  }
+
+  private _resolveExecutable(exec: string): string | null {
+    // Absolute path — check existence
+    if (path.isAbsolute(exec)) {
+      if (fs.existsSync(exec)) {return exec;}
+      // Try with .exe on Windows
+      if (process.platform === 'win32' && !exec.endsWith('.exe')) {
+        const withExt = exec + '.exe';
+        if (fs.existsSync(withExt)) {return withExt;}
+      }
+      return null;
+    }
+
+    // Relative name — resolve via which
+    return this._which(exec);
+  }
+
+  private _which(name: string): string | null {
+    try {
+      const cmd = process.platform === 'win32' ? `where ${name}` : `which ${name}`;
+      const result = execSync(cmd, {
+        encoding: 'utf8',
+        timeout:  3000,
+        stdio:    ['pipe', 'pipe', 'pipe'],
+      }).trim();
+
+      // `where` returns multiple lines; take the first
+      const first = result.split(/\r?\n/)[0]?.trim();
+      return first || null;
+    } catch {
+      return null;
+    }
+  }
+
+  private _meetsVersionRequirement(info: PythonInfo): boolean {
+    const [minMajor, minMinor] = this._opts.minVersion;
+    if (info.major !== minMajor!) {return info.major > minMajor!;}
+    return info.minor >= minMinor!;
+  }
+
+  private _checkModules(executable: string, modules: string[]): string[] {
+    if (modules.length === 0) {return [];}
+
+    const script = modules
+      .map(m => `try:\n    import ${m}\nexcept ImportError:\n    print("MISSING:${m}")`)
+      .join('\n');
+
+    try {
+      const result = spawnSync(executable, ['-c', script], {
+        encoding:  'utf8',
+        timeout:   this._opts.timeout,
+        maxBuffer: 1024 * 256,
+      });
+
+      const missing: string[] = [];
+      for (const line of (result.stdout ?? '').split('\n')) {
+        const match = line.match(/^MISSING:(.+)$/);
+        if (match) {missing.push(match[1]!);}
+      }
+      return missing;
+    } catch {
+      return modules; // assume all missing if we can't check
+    }
+  }
+}
+
+// ─── Error types ─────────────────────────────────────────────────────────────
+
+export class PythonNotFoundError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'PythonNotFoundError';
+  }
+}
+
+export class PythonVersionError extends Error {
+  constructor(found: string, required: string) {
+    super(
+      `Python ${found} is below the minimum required version ${required}. ` +
+      `Please upgrade Python.`,
+    );
+    this.name = 'PythonVersionError';
+  }
+}
+