nodepyx 1.0.0

package/src/env/VenvManager.ts

@@ -0,0 +1,396 @@
+/**
+ * nodepyx — VenvManager
+ * Creates and manages Python virtualenvs for isolated package installation.
+ *
+ * Lifecycle:
+ *   1. Check if the venv directory exists and is valid.
+ *   2. If not, run `python3 -m venv <path>` to create it.
+ *   3. Upgrade pip to the latest version.
+ *   4. Install configured packages via pip.
+ *   5. Return the path to the Python executable inside the venv.
+ *
+ * State file (.nodepyx/venv-state.json) tracks installed packages
+ * to avoid re-running pip on every startup.
+ */
+
+import { spawnSync } from 'child_process';
+import * as fs   from 'fs';
+import * as path from 'path';
+import { Logger } from '../utils/Logger';
+import type { VirtualenvConfig } from '../types/config';
+
+const logger = new Logger('VenvManager');
+
+// ─── Types ─────────────────────────────────────────────────────────────────
+
+export interface VenvState {
+  /** Venv creation timestamp */
+  createdAt: number;
+  /** Python version used to create the venv */
+  pythonVersion: string;
+  /** Packages that have been installed (pip-freeze style name==version) */
+  installedPackages: string[];
+  /** Last pip install timestamp */
+  lastInstallAt: number;
+}
+
+export interface VenvSetupResult {
+  /** Absolute path to Python executable inside the venv */
+  pythonExecutable: string;
+  /** Absolute path to pip executable */
+  pipExecutable: string;
+  /** Whether the venv was newly created */
+  created: boolean;
+  /** Whether packages were (re)installed */
+  packagesInstalled: boolean;
+}
+
+export interface VenvManagerOptions {
+  /** Virtualenv config from nodepyxConfig */
+  virtualenv: VirtualenvConfig;
+  /** Base Python executable to use for creating the venv */
+  basePython?: string;
+  /** Timeout for pip install in ms. Default: 300000 (5 minutes) */
+  installTimeout?: number;
+  /** Skip upgrading pip. Default: false */
+  skipPipUpgrade?: boolean;
+}
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+function isWindows(): boolean {
+  return process.platform === 'win32';
+}
+
+function venvBinDir(venvPath: string): string {
+  return path.join(venvPath, isWindows() ? 'Scripts' : 'bin');
+}
+
+function venvPython(venvPath: string): string {
+  return path.join(
+    venvBinDir(venvPath),
+    isWindows() ? 'python.exe' : 'python3',
+  );
+}
+
+function venvPip(venvPath: string): string {
+  return path.join(
+    venvBinDir(venvPath),
+    isWindows() ? 'pip.exe' : 'pip3',
+  );
+}
+
+const STATE_FILENAME = '.nodepyx-venv-state.json';
+
+/**
+ * VenvManager — creates and manages Python virtualenvs.
+ *
+ * @example
+ * ```typescript
+ * const manager = new VenvManager({
+ *   virtualenv: {
+ *     path: './.venv',
+ *     packages: ['pandas', 'numpy', 'scikit-learn'],
+ *     autoInstall: true,
+ *   }
+ * });
+ *
+ * const result = await manager.setup();
+ * console.log(result.pythonExecutable);  // ./.venv/bin/python3
+ * ```
+ */
+export class VenvManager {
+  private readonly _config: VirtualenvConfig;
+  private readonly _basePython: string;
+  private readonly _installTimeout: number;
+  private readonly _skipPipUpgrade: boolean;
+  private readonly _venvPath: string;
+  private readonly _statePath: string;
+
+  constructor(options: VenvManagerOptions) {
+    this._config         = options.virtualenv;
+    this._basePython     = options.basePython     ?? 'python3';
+    this._installTimeout = options.installTimeout  ?? 300_000;
+    this._skipPipUpgrade = options.skipPipUpgrade  ?? false;
+    this._venvPath       = path.resolve(this._config.path);
+    this._statePath      = path.join(this._venvPath, STATE_FILENAME);
+  }
+
+  // ─── Public API ──────────────────────────────────────────────────────────
+
+  /**
+   * Set up the virtualenv and install packages if needed.
+   * Returns the path to the Python executable inside the venv.
+   */
+  async setup(): Promise<VenvSetupResult> {
+    let created = false;
+    let packagesInstalled = false;
+
+    // ── Create venv if it doesn't exist ──────────────────────────────────
+    if (!this._venvExists()) {
+      logger.info(`VenvManager: creating virtualenv at ${this._venvPath}`);
+      this._createVenv();
+      created = true;
+
+      if (!this._skipPipUpgrade) {
+        this._upgradePip();
+      }
+    }
+
+    const pythonExec = venvPython(this._venvPath);
+    const pipExec    = venvPip(this._venvPath);
+
+    // ── Install packages ─────────────────────────────────────────────────
+    if (this._config.autoInstall && this._config.packages.length > 0) {
+      const missingPackages = this._findMissingPackages(pythonExec);
+
+      if (missingPackages.length > 0 || created) {
+        logger.info(`VenvManager: installing ${missingPackages.length > 0 ? missingPackages.join(', ') : this._config.packages.join(', ')}`);
+        this._installPackages(
+          pipExec,
+          missingPackages.length > 0 ? missingPackages : this._config.packages,
+        );
+        packagesInstalled = true;
+        this._updateState(pythonExec);
+      }
+    }
+
+    logger.info(`VenvManager: ready — ${pythonExec}`);
+
+    return {
+      pythonExecutable: pythonExec,
+      pipExecutable:    pipExec,
+      created,
+      packagesInstalled,
+    };
+  }
+
+  /**
+   * Install additional packages into the venv.
+   */
+  async install(packages: string[]): Promise<void> {
+    if (!this._venvExists()) {
+      throw new Error(`VenvManager: venv does not exist at ${this._venvPath}`);
+    }
+    const pip = venvPip(this._venvPath);
+    this._installPackages(pip, packages);
+    this._updateState(venvPython(this._venvPath));
+  }
+
+  /**
+   * Check which of the configured packages are not installed in the venv.
+   */
+  getMissingPackages(): string[] {
+    if (!this._venvExists()) {return this._config.packages;}
+    return this._findMissingPackages(venvPython(this._venvPath));
+  }
+
+  /**
+   * Return the Python executable path inside the venv (without setup).
+   */
+  get pythonExecutable(): string {
+    return venvPython(this._venvPath);
+  }
+
+  /**
+   * Return true if the venv exists and appears valid.
+   */
+  isValid(): boolean {
+    return this._venvExists();
+  }
+
+  /**
+   * Destroy the venv directory.
+   */
+  destroy(): void {
+    if (fs.existsSync(this._venvPath)) {
+      fs.rmSync(this._venvPath, { recursive: true, force: true });
+      logger.info(`VenvManager: destroyed venv at ${this._venvPath}`);
+    }
+  }
+
+  /**
+   * Return the list of installed packages (pip freeze format).
+   */
+  listInstalled(): string[] {
+    const state = this._loadState();
+    return state?.installedPackages ?? [];
+  }
+
+  // ─── Private ─────────────────────────────────────────────────────────────
+
+  private _venvExists(): boolean {
+    const pyExec = venvPython(this._venvPath);
+    return fs.existsSync(pyExec);
+  }
+
+  private _createVenv(): void {
+    fs.mkdirSync(path.dirname(this._venvPath), { recursive: true });
+
+    // Try with pyvenv-cfg check
+    const result = spawnSync(
+      this._basePython,
+      ['-m', 'venv', '--clear', this._venvPath],
+      {
+        encoding: 'utf8',
+        timeout:  60_000,
+        stdio:    'pipe',
+      },
+    );
+
+    if (result.status !== 0) {
+      const err = result.stderr?.trim() || result.error?.message || 'unknown error';
+      throw new VenvCreationError(
+        `Failed to create virtualenv at ${this._venvPath}: ${err}`,
+      );
+    }
+
+    logger.info(`VenvManager: virtualenv created at ${this._venvPath}`);
+  }
+
+  private _upgradePip(): void {
+    const pip = venvPip(this._venvPath);
+    try {
+      const result = spawnSync(
+        pip,
+        ['install', '--upgrade', 'pip', '--quiet'],
+        { encoding: 'utf8', timeout: 60_000, stdio: 'pipe' },
+      );
+      if (result.status === 0) {
+        logger.debug('VenvManager: pip upgraded');
+      }
+    } catch {
+      logger.warn('VenvManager: pip upgrade failed (continuing)');
+    }
+  }
+
+  private _installPackages(pip: string, packages: string[]): void {
+    if (packages.length === 0) {return;}
+
+    const args = ['install', '--quiet', ...packages];
+
+    if (this._config.pipIndexUrl) {
+      args.push('--index-url', this._config.pipIndexUrl);
+    }
+
+    if (this._config.pipArgs) {
+      args.push(...this._config.pipArgs);
+    }
+
+    logger.info(`VenvManager: running pip install ${packages.join(' ')}`);
+
+    const result = spawnSync(pip, args, {
+      encoding:  'utf8',
+      timeout:   this._installTimeout,
+      stdio:     ['ignore', 'pipe', 'pipe'],
+    });
+
+    if (result.status !== 0) {
+      const err = result.stderr?.trim() || 'pip install failed';
+      throw new PackageInstallError(packages, err);
+    }
+  }
+
+  private _findMissingPackages(pythonExec: string): string[] {
+    const state = this._loadState();
+    if (!state) {return this._config.packages;}
+
+    // Quick check via import
+    const missing: string[] = [];
+    for (const pkg of this._config.packages) {
+      // Strip version specifiers for import test
+      const importName = this._packageToImportName(pkg);
+      const result = spawnSync(
+        pythonExec,
+        ['-c', `import ${importName}`],
+        { encoding: 'utf8', timeout: 5000, stdio: 'pipe' },
+      );
+      if (result.status !== 0) {
+        missing.push(pkg);
+      }
+    }
+
+    return missing;
+  }
+
+  private _packageToImportName(pkg: string): string {
+    // Strip version specifiers: pandas>=2.0 → pandas
+    const stripped = pkg.replace(/[>=<!].*/g, '').trim();
+    // Normalize: scikit-learn → sklearn, Pillow → PIL
+    const importAliases: Record<string, string> = {
+      'scikit-learn': 'sklearn',
+      'scikit_learn': 'sklearn',
+      'Pillow':        'PIL',
+      'pillow':        'PIL',
+      'opencv-python': 'cv2',
+      'pyyaml':        'yaml',
+      'beautifulsoup4': 'bs4',
+    };
+    return importAliases[stripped] ?? stripped;
+  }
+
+  private _updateState(pythonExec: string): void {
+    try {
+      const result = spawnSync(
+        pythonExec,
+        ['-m', 'pip', 'freeze', '--quiet'],
+        { encoding: 'utf8', timeout: 30_000, stdio: 'pipe' },
+      );
+      const installed = (result.stdout ?? '').trim().split('\n').filter(Boolean);
+
+      const state: VenvState = {
+        createdAt:         this._loadState()?.createdAt ?? Date.now(),
+        pythonVersion:     this._getPythonVersion(pythonExec),
+        installedPackages: installed,
+        lastInstallAt:     Date.now(),
+      };
+
+      fs.writeFileSync(this._statePath, JSON.stringify(state, null, 2), 'utf8');
+    } catch (err) {
+      logger.warn('VenvManager: failed to update state file', err);
+    }
+  }
+
+  private _loadState(): VenvState | null {
+    try {
+      if (fs.existsSync(this._statePath)) {
+        return JSON.parse(fs.readFileSync(this._statePath, 'utf8')) as VenvState;
+      }
+    } catch {
+      // ignore
+    }
+    return null;
+  }
+
+  private _getPythonVersion(pythonExec: string): string {
+    try {
+      const result = spawnSync(pythonExec, ['--version'], {
+        encoding: 'utf8',
+        timeout:  5000,
+        stdio:    'pipe',
+      });
+      return (result.stdout || result.stderr || '').trim().replace('Python ', '');
+    } catch {
+      return 'unknown';
+    }
+  }
+}
+
+// ─── Error types ─────────────────────────────────────────────────────────────
+
+export class VenvCreationError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'VenvCreationError';
+  }
+}
+
+export class PackageInstallError extends Error {
+  readonly packages: string[];
+  constructor(packages: string[], detail: string) {
+    super(`Failed to install packages [${packages.join(', ')}]: ${detail}`);
+    this.name    = 'PackageInstallError';
+    this.packages = packages;
+  }
+}
+