nodepyx 1.0.0

package/dist/env/PythonDetector.d.ts

@@ -0,0 +1,103 @@
+/**
+ * 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)
+ */
+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[];
+}
+/**
+ * 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 declare class PythonDetector {
+    private readonly _opts;
+    constructor(options?: DetectorOptions);
+    /**
+     * Detect and validate a Python interpreter.
+     * Returns the first suitable interpreter found.
+     * Throws if no suitable interpreter is found.
+     */
+    detect(): Promise<PythonInfo>;
+    /**
+     * 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;
+    /**
+     * Check if a Python executable meets the minimum version requirement.
+     */
+    isCompatible(info: PythonInfo): boolean;
+    /**
+     * 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[];
+    /**
+     * List all Python executables found in common locations and PATH.
+     */
+    listAll(): Promise<PythonInfo[]>;
+    private _buildCandidates;
+    private _probe;
+    private _resolveExecutable;
+    private _which;
+    private _meetsVersionRequirement;
+    private _checkModules;
+}
+export declare class PythonNotFoundError extends Error {
+    constructor(message: string);
+}
+export declare class PythonVersionError extends Error {
+    constructor(found: string, required: string);
+}
+//# sourceMappingURL=PythonDetector.d.ts.map

package/dist/env/PythonDetector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PythonDetector.d.ts","sourceRoot":"","sources":["../../src/env/PythonDetector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAWH,MAAM,WAAW,UAAU;IACzB,yCAAyC;IACzC,UAAU,EAAE,MAAM,CAAC;IACnB,4CAA4C;IAC5C,OAAO,EAAE,MAAM,CAAC;IAChB,6BAA6B;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,kDAAkD;IAClD,MAAM,EAAE,MAAM,CAAC;IACf,0CAA0C;IAC1C,YAAY,EAAE,OAAO,CAAC;IACtB,iDAAiD;IACjD,OAAO,EAAE,OAAO,CAAC;IACjB,6CAA6C;IAC7C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,6CAA6C;IAC7C,QAAQ,EAAE,MAAM,CAAC;IACjB,oCAAoC;IACpC,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,eAAe;IAC9B,uDAAuD;IACvD,UAAU,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9B,mCAAmC;IACnC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,wDAAwD;IACxD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,sEAAsE;IACtE,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,mDAAmD;IACnD,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;CAC5B;AA0ED;;;;;;;;;;GAUG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA4B;gBAEtC,OAAO,GAAE,eAAoB;IAYzC;;;;OAIG;IACG,MAAM,IAAI,OAAO,CAAC,UAAU,CAAC;IAkCnC;;;OAGG;IACH,KAAK,CAAC,cAAc,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI;IAIhD;;OAEG;IACH,YAAY,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO;IAIvC;;;OAGG;IACH,YAAY,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE;IAI7D;;OAEG;IACG,OAAO,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC;IActC,OAAO,CAAC,gBAAgB;IAuCxB,OAAO,CAAC,MAAM;IAmDd,OAAO,CAAC,kBAAkB;IAgB1B,OAAO,CAAC,MAAM;IAiBd,OAAO,CAAC,wBAAwB;IAMhC,OAAO,CAAC,aAAa;CAwBtB;AAID,qBAAa,mBAAoB,SAAQ,KAAK;gBAChC,OAAO,EAAE,MAAM;CAI5B;AAED,qBAAa,kBAAmB,SAAQ,KAAK;gBAC/B,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM;CAO5C"}

package/dist/env/PythonDetector.js

@@ -0,0 +1,381 @@
+"use strict";
+/**
+ * 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)
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PythonVersionError = exports.PythonNotFoundError = exports.PythonDetector = void 0;
+const child_process_1 = require("child_process");
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const Logger_1 = require("../utils/Logger");
+const logger = new Logger_1.Logger('PythonDetector');
+// ─── Platform-specific common locations ─────────────────────────────────────
+const COMMON_LOCATIONS = {
+    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: [],
+};
+// 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
+ * ```
+ */
+class PythonDetector {
+    _opts;
+    constructor(options = {}) {
+        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() {
+        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) {
+        return this._probe(executablePath);
+    }
+    /**
+     * Check if a Python executable meets the minimum version requirement.
+     */
+    isCompatible(info) {
+        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, modules) {
+        return this._checkModules(executable, modules);
+    }
+    /**
+     * List all Python executables found in common locations and PATH.
+     */
+    async listAll() {
+        const results = [];
+        const candidates = this._buildCandidates();
+        for (const candidate of candidates) {
+            const info = this._probe(candidate);
+            if (info) {
+                results.push(info);
+            }
+        }
+        return results;
+    }
+    // ─── Private ─────────────────────────────────────────────────────────────
+    _buildCandidates() {
+        const candidates = [];
+        // 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;
+        for (const loc of COMMON_LOCATIONS[platformKey] ?? []) {
+            if (loc) {
+                candidates.push(loc);
+            }
+        }
+        // Deduplicate while preserving order
+        return [...new Set(candidates)];
+    }
+    _probe(executable) {
+        if (!executable) {
+            return null;
+        }
+        try {
+            // Resolve Windows executable extension
+            const exec = this._resolveExecutable(executable);
+            if (!exec) {
+                return null;
+            }
+            const result = (0, child_process_1.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());
+            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;
+        }
+    }
+    _resolveExecutable(exec) {
+        // 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);
+    }
+    _which(name) {
+        try {
+            const cmd = process.platform === 'win32' ? `where ${name}` : `which ${name}`;
+            const result = (0, child_process_1.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;
+        }
+    }
+    _meetsVersionRequirement(info) {
+        const [minMajor, minMinor] = this._opts.minVersion;
+        if (info.major !== minMajor) {
+            return info.major > minMajor;
+        }
+        return info.minor >= minMinor;
+    }
+    _checkModules(executable, modules) {
+        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 = (0, child_process_1.spawnSync)(executable, ['-c', script], {
+                encoding: 'utf8',
+                timeout: this._opts.timeout,
+                maxBuffer: 1024 * 256,
+            });
+            const missing = [];
+            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
+        }
+    }
+}
+exports.PythonDetector = PythonDetector;
+// ─── Error types ─────────────────────────────────────────────────────────────
+class PythonNotFoundError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'PythonNotFoundError';
+    }
+}
+exports.PythonNotFoundError = PythonNotFoundError;
+class PythonVersionError extends Error {
+    constructor(found, required) {
+        super(`Python ${found} is below the minimum required version ${required}. ` +
+            `Please upgrade Python.`);
+        this.name = 'PythonVersionError';
+    }
+}
+exports.PythonVersionError = PythonVersionError;
+//# sourceMappingURL=PythonDetector.js.map

package/dist/env/PythonDetector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"PythonDetector.js","sourceRoot":"","sources":["../../src/env/PythonDetector.ts"],"names":[],"mappings":"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"}

package/dist/env/VenvManager.d.ts

@@ -0,0 +1,117 @@
+/**
+ * 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 type { VirtualenvConfig } from '../types/config';
+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;
+}
+/**
+ * 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 declare class VenvManager {
+    private readonly _config;
+    private readonly _basePython;
+    private readonly _installTimeout;
+    private readonly _skipPipUpgrade;
+    private readonly _venvPath;
+    private readonly _statePath;
+    constructor(options: VenvManagerOptions);
+    /**
+     * Set up the virtualenv and install packages if needed.
+     * Returns the path to the Python executable inside the venv.
+     */
+    setup(): Promise<VenvSetupResult>;
+    /**
+     * Install additional packages into the venv.
+     */
+    install(packages: string[]): Promise<void>;
+    /**
+     * Check which of the configured packages are not installed in the venv.
+     */
+    getMissingPackages(): string[];
+    /**
+     * Return the Python executable path inside the venv (without setup).
+     */
+    get pythonExecutable(): string;
+    /**
+     * Return true if the venv exists and appears valid.
+     */
+    isValid(): boolean;
+    /**
+     * Destroy the venv directory.
+     */
+    destroy(): void;
+    /**
+     * Return the list of installed packages (pip freeze format).
+     */
+    listInstalled(): string[];
+    private _venvExists;
+    private _createVenv;
+    private _upgradePip;
+    private _installPackages;
+    private _findMissingPackages;
+    private _packageToImportName;
+    private _updateState;
+    private _loadState;
+    private _getPythonVersion;
+}
+export declare class VenvCreationError extends Error {
+    constructor(message: string);
+}
+export declare class PackageInstallError extends Error {
+    readonly packages: string[];
+    constructor(packages: string[], detail: string);
+}
+//# sourceMappingURL=VenvManager.d.ts.map

package/dist/env/VenvManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"VenvManager.d.ts","sourceRoot":"","sources":["../../src/env/VenvManager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAMH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAMxD,MAAM,WAAW,SAAS;IACxB,8BAA8B;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,6CAA6C;IAC7C,aAAa,EAAE,MAAM,CAAC;IACtB,yEAAyE;IACzE,iBAAiB,EAAE,MAAM,EAAE,CAAC;IAC5B,iCAAiC;IACjC,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,eAAe;IAC9B,yDAAyD;IACzD,gBAAgB,EAAE,MAAM,CAAC;IACzB,sCAAsC;IACtC,aAAa,EAAE,MAAM,CAAC;IACtB,yCAAyC;IACzC,OAAO,EAAE,OAAO,CAAC;IACjB,0CAA0C;IAC1C,iBAAiB,EAAE,OAAO,CAAC;CAC5B;AAED,MAAM,WAAW,kBAAkB;IACjC,2CAA2C;IAC3C,UAAU,EAAE,gBAAgB,CAAC;IAC7B,0DAA0D;IAC1D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,iEAAiE;IACjE,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,yCAAyC;IACzC,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AA4BD;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAmB;IAC3C,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAS;IACzC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAU;IAC1C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;gBAExB,OAAO,EAAE,kBAAkB;IAWvC;;;OAGG;IACG,KAAK,IAAI,OAAO,CAAC,eAAe,CAAC;IA2CvC;;OAEG;IACG,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAShD;;OAEG;IACH,kBAAkB,IAAI,MAAM,EAAE;IAK9B;;OAEG;IACH,IAAI,gBAAgB,IAAI,MAAM,CAE7B;IAED;;OAEG;IACH,OAAO,IAAI,OAAO;IAIlB;;OAEG;IACH,OAAO,IAAI,IAAI;IAOf;;OAEG;IACH,aAAa,IAAI,MAAM,EAAE;IAOzB,OAAO,CAAC,WAAW;IAKnB,OAAO,CAAC,WAAW;IAwBnB,OAAO,CAAC,WAAW;IAgBnB,OAAO,CAAC,gBAAgB;IA2BxB,OAAO,CAAC,oBAAoB;IAsB5B,OAAO,CAAC,oBAAoB;IAgB5B,OAAO,CAAC,YAAY;IAsBpB,OAAO,CAAC,UAAU;IAWlB,OAAO,CAAC,iBAAiB;CAY1B;AAID,qBAAa,iBAAkB,SAAQ,KAAK;gBAC9B,OAAO,EAAE,MAAM;CAI5B;AAED,qBAAa,mBAAoB,SAAQ,KAAK;IAC5C,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,CAAC;gBAChB,QAAQ,EAAE,MAAM,EAAE,EAAE,MAAM,EAAE,MAAM;CAK/C"}