nebula-notebook 0.1.0

package/node-server/dist/discovery/discovery-service.js

@@ -0,0 +1,811 @@
+"use strict";
+/**
+ * Python Discovery Service
+ *
+ * Discovers Python environments on the system (conda, pyenv, venv, system).
+ * Node.js port of the Python PythonDiscoveryService.
+ */
+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.pythonDiscovery = exports.PythonDiscoveryService = void 0;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const os = __importStar(require("os"));
+const child_process_1 = require("child_process");
+const types_1 = require("./types");
+const DEFAULT_CACHE_FILE = path.join(os.homedir(), '.nebula-notebook', 'python-cache.json');
+class PythonDiscoveryService {
+    cache = {};
+    cacheTimestamp = 0;
+    cacheFile;
+    cacheTtlHours;
+    versionCheckTimeoutMs;
+    ipykernelCheckTimeoutMs;
+    condaListTimeoutMs;
+    kernelInstallTimeoutMs;
+    registrationTimeoutMs;
+    backgroundRefreshInProgress = false;
+    constructor(options = {}) {
+        this.cacheFile = options.cacheFile || DEFAULT_CACHE_FILE;
+        this.cacheTtlHours = options.cacheTtlHours ?? types_1.DEFAULT_CACHE_TTL_HOURS;
+        this.versionCheckTimeoutMs = options.versionCheckTimeoutMs ?? types_1.DEFAULT_VERSION_CHECK_TIMEOUT_MS;
+        this.ipykernelCheckTimeoutMs = options.ipykernelCheckTimeoutMs ?? types_1.DEFAULT_IPYKERNEL_CHECK_TIMEOUT_MS;
+        this.condaListTimeoutMs = options.condaListTimeoutMs ?? types_1.DEFAULT_CONDA_LIST_TIMEOUT_MS;
+        this.kernelInstallTimeoutMs = options.kernelInstallTimeoutMs ?? types_1.DEFAULT_KERNEL_INSTALL_TIMEOUT_MS;
+        this.registrationTimeoutMs = options.registrationTimeoutMs ?? types_1.DEFAULT_REGISTRATION_TIMEOUT_MS;
+        this.loadCache();
+    }
+    /**
+     * Load cache from disk
+     */
+    loadCache() {
+        try {
+            if (fs.existsSync(this.cacheFile)) {
+                const data = JSON.parse(fs.readFileSync(this.cacheFile, 'utf-8'));
+                this.cache = data.environments || {};
+                this.cacheTimestamp = data.timestamp || 0;
+            }
+        }
+        catch (e) {
+            console.warn('Failed to load Python cache:', e);
+            this.cache = {};
+            this.cacheTimestamp = 0;
+        }
+    }
+    /**
+     * Save environments to cache
+     */
+    saveToCache(environments) {
+        try {
+            const dir = path.dirname(this.cacheFile);
+            if (!fs.existsSync(dir)) {
+                fs.mkdirSync(dir, { recursive: true });
+            }
+            const data = {
+                environments,
+                timestamp: Date.now(),
+            };
+            fs.writeFileSync(this.cacheFile, JSON.stringify(data, null, 2), 'utf-8');
+            this.cache = environments;
+            this.cacheTimestamp = data.timestamp;
+        }
+        catch (e) {
+            console.warn('Failed to save Python cache:', e);
+        }
+    }
+    /**
+     * Get environments from cache (returns null if empty)
+     */
+    getFromCache() {
+        if (Object.keys(this.cache).length === 0) {
+            return null;
+        }
+        return this.cache;
+    }
+    /**
+     * Check if cache is still valid
+     */
+    isCacheValid() {
+        if (Object.keys(this.cache).length === 0) {
+            return false;
+        }
+        const ageHours = (Date.now() - this.cacheTimestamp) / (1000 * 60 * 60);
+        return ageHours < this.cacheTtlHours;
+    }
+    /**
+     * Get cache info
+     */
+    getCacheInfo() {
+        return {
+            cachedCount: Object.keys(this.cache).length,
+            cacheAgeHours: this.cacheTimestamp > 0 ? (Date.now() - this.cacheTimestamp) / (1000 * 60 * 60) : null,
+            cacheValid: this.isCacheValid(),
+            cacheFile: this.cacheFile,
+            refreshing: this.backgroundRefreshInProgress,
+        };
+    }
+    /**
+     * Run a command asynchronously with timeout
+     */
+    runCommand(command, args, timeoutMs) {
+        return new Promise((resolve, reject) => {
+            const child = (0, child_process_1.spawn)(command, args, { stdio: ['ignore', 'pipe', 'pipe'] });
+            let stdout = '';
+            let stderr = '';
+            let finished = false;
+            const timer = timeoutMs > 0 ? setTimeout(() => {
+                if (finished)
+                    return;
+                finished = true;
+                child.kill('SIGKILL');
+                reject(new Error(`Command timed out after ${timeoutMs}ms`));
+            }, timeoutMs) : null;
+            child.stdout?.on('data', (data) => {
+                stdout += data.toString();
+            });
+            child.stderr?.on('data', (data) => {
+                stderr += data.toString();
+            });
+            child.on('error', (err) => {
+                if (finished)
+                    return;
+                finished = true;
+                if (timer)
+                    clearTimeout(timer);
+                reject(err);
+            });
+            child.on('close', (code) => {
+                if (finished)
+                    return;
+                finished = true;
+                if (timer)
+                    clearTimeout(timer);
+                if (code === 0) {
+                    resolve({ stdout, stderr });
+                }
+                else {
+                    reject(new Error(`Command failed with code ${code}: ${stderr || stdout}`));
+                }
+            });
+        });
+    }
+    /**
+     * Generate display name for an environment
+     */
+    generateDisplayName(version, envType, envName) {
+        if (envType === 'conda' && envName) {
+            return `Python ${version} (conda: ${envName})`;
+        }
+        else if (envType === 'pyenv' && envName) {
+            return `Python ${version} (pyenv: ${envName})`;
+        }
+        else if (envType === 'venv' && envName) {
+            return `Python ${version} (venv: ${envName})`;
+        }
+        else if (envType === 'pixi') {
+            return `Python ${version} (pixi${envName ? `: ${envName}` : ''})`;
+        }
+        else if (envType === 'uv') {
+            return `Python ${version} (uv-managed)`;
+        }
+        else if (envType === 'homebrew') {
+            return `Python ${version} (Homebrew)`;
+        }
+        return `Python ${version} (System)`;
+    }
+    /**
+     * Sort environments by type priority and name
+     */
+    sortEnvironments(envs) {
+        const typeOrder = {
+            conda: 0,
+            pyenv: 1,
+            venv: 2,
+            pixi: 3,
+            uv: 4,
+            homebrew: 5,
+            system: 6,
+        };
+        return [...envs].sort((a, b) => {
+            const typeA = typeOrder[a.envType] ?? 99;
+            const typeB = typeOrder[b.envType] ?? 99;
+            if (typeA !== typeB) {
+                return typeA - typeB;
+            }
+            return a.displayName.localeCompare(b.displayName);
+        });
+    }
+    /**
+     * Check if a python path exists
+     */
+    pythonExists(pythonPath) {
+        return fs.existsSync(pythonPath);
+    }
+    /**
+     * Get common conda base paths to search
+     */
+    getCondaBasePaths() {
+        const home = os.homedir();
+        return [
+            path.join(home, 'anaconda3'),
+            path.join(home, 'miniconda3'),
+            path.join(home, 'miniforge3'),
+            path.join(home, 'mambaforge'),
+            '/opt/anaconda3',
+            '/opt/miniconda3',
+            '/opt/homebrew/anaconda3',
+            '/usr/local/anaconda3',
+            '/usr/local/miniconda3',
+        ];
+    }
+    /**
+     * Get common system python paths
+     */
+    getSystemPythonPaths() {
+        const paths = [
+            '/usr/bin/python3',
+            '/usr/local/bin/python3',
+            '/opt/homebrew/bin/python3', // Apple Silicon Homebrew
+            '/usr/local/opt/python/libexec/bin/python', // Intel Homebrew
+        ];
+        // Add paths from PATH environment
+        const envPath = process.env.PATH || '';
+        for (const dir of envPath.split(':')) {
+            for (const name of ['python3', 'python']) {
+                const candidate = path.join(dir, name);
+                if (!paths.includes(candidate)) {
+                    paths.push(candidate);
+                }
+            }
+        }
+        return paths;
+    }
+    /**
+     * Get pyenv versions path
+     */
+    getPyenvVersionsPath() {
+        return path.join(os.homedir(), '.pyenv', 'versions');
+    }
+    /**
+     * Get common virtualenv paths
+     */
+    getVirtualenvPaths() {
+        const home = os.homedir();
+        return [
+            path.join(home, '.virtualenvs'),
+            path.join(home, 'venvs'),
+            path.join(home, '.venvs'),
+        ];
+    }
+    /**
+     * Generate a unique kernel name from path
+     */
+    generateKernelName(pythonPath, version) {
+        const versionShort = version.split('.').slice(0, 2).join('.');
+        const pathHash = Math.abs(this.hashString(pythonPath)) % 10000;
+        return `python${versionShort}_${pathHash}`;
+    }
+    /**
+     * Simple string hash function
+     */
+    hashString(str) {
+        let hash = 0;
+        for (let i = 0; i < str.length; i++) {
+            const char = str.charCodeAt(i);
+            hash = ((hash << 5) - hash) + char;
+            hash = hash & hash; // Convert to 32bit integer
+        }
+        return hash;
+    }
+    /**
+     * Parse Python version from version string
+     */
+    parseVersionString(versionOutput) {
+        const match = versionOutput.match(/Python (\d+\.\d+\.\d+)/);
+        if (match) {
+            return match[1];
+        }
+        // Try without patch version
+        const match2 = versionOutput.match(/Python (\d+\.\d+)/);
+        if (match2) {
+            return match2[1];
+        }
+        return versionOutput.replace('Python ', '').trim();
+    }
+    /**
+     * Get Python version from executable
+     */
+    async getPythonVersion(pythonPath) {
+        try {
+            const { stdout, stderr } = await this.runCommand(pythonPath, ['--version'], this.versionCheckTimeoutMs);
+            const output = (stdout || stderr).trim();
+            return this.parseVersionString(output);
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Check if ipykernel is installed
+     */
+    async checkIpykernel(pythonPath) {
+        return (await this.probeEnvironment(pythonPath)).hasIpykernel;
+    }
+    /**
+     * Probe an interpreter for the two facts that drive kernel provisioning, in a
+     * single Python invocation (keeps discovery cheap — one spawn per env):
+     *   - whether `ipykernel` is importable
+     *   - whether the interpreter is PEP 668 "externally managed" (an
+     *     `EXTERNALLY-MANAGED` marker beside the stdlib), which blocks pip installs.
+     *
+     * Detecting the marker file is capability-based and stable: we ask Python
+     * itself rather than fingerprinting tool names by path, so it keeps working as
+     * new package managers (uv, pixi, …) appear.
+     */
+    async probeEnvironment(pythonPath) {
+        const script = [
+            'import json, os, sys, sysconfig',
+            'from importlib.util import find_spec',
+            'stdlib = sysconfig.get_path("stdlib") or ""',
+            'marker = bool(stdlib) and os.path.exists(os.path.join(stdlib, "EXTERNALLY-MANAGED"))',
+            // A virtual environment always allows pip installs — PEP 668 enforcement is
+            // skipped inside venvs (pip checks sys.prefix != sys.base_prefix), even when
+            // the venv's base interpreter carries the EXTERNALLY-MANAGED marker.
+            'in_venv = sys.prefix != sys.base_prefix',
+            'em = marker and not in_venv',
+            'ik = find_spec("ipykernel") is not None',
+            'print(json.dumps({"ipykernel": ik, "externally_managed": em, "venv": in_venv}))',
+        ].join('; ');
+        try {
+            const { stdout } = await this.runCommand(pythonPath, ['-c', script], this.ipykernelCheckTimeoutMs);
+            const parsed = JSON.parse(stdout.trim().split('\n').pop() || '{}');
+            return {
+                hasIpykernel: !!parsed.ipykernel,
+                externallyManaged: !!parsed.externally_managed,
+                isVenv: !!parsed.venv,
+            };
+        }
+        catch {
+            return { hasIpykernel: false, externallyManaged: false, isVenv: false };
+        }
+    }
+    /**
+     * Refine an environment's type using stable path markers that the coarse
+     * discovery scans miss. Only used to pick a better label / guidance hint —
+     * the safe-vs-unsafe install decision relies on `externallyManaged`, not this.
+     *
+     * A venv is left as-is: its `bin/python` symlinks to (and `sysconfig` resolves
+     * to) its base interpreter, so following the symlink to e.g. a uv-managed build
+     * must NOT relabel the venv itself as "uv".
+     */
+    classifyEnvType(originalPath, realPath, current, isVenv) {
+        const o = originalPath.replace(/\\/g, '/');
+        const r = realPath.replace(/\\/g, '/');
+        if (o.includes('/.pixi/envs/') || r.includes('/.pixi/envs/'))
+            return 'pixi';
+        // uv-managed standalone interpreters live under .../uv/python/cpython-* . Only
+        // a bare interpreter qualifies — a venv built on one stays a venv.
+        if (!isVenv && (r.includes('/uv/python/') || r.includes('/.local/share/uv/')))
+            return 'uv';
+        return current;
+    }
+    /**
+     * Build a copy-pasteable command that makes `ipykernel` available for an env,
+     * tailored to the detected ecosystem. After the user runs it (and clicks
+     * Refresh), the env shows up with ipykernel and Nebula offers one-click
+     * Register — Nebula never installs packages itself.
+     *
+     * Returns null when ipykernel is already present (nothing to do but Register).
+     */
+    buildInstallHint(pythonPath, envType, envName, hasIpykernel, externallyManaged) {
+        if (hasIpykernel)
+            return null;
+        const py = pythonPath.includes(' ') ? `"${pythonPath}"` : pythonPath;
+        // Installable in place: not externally managed → use the env's own manager.
+        if (!externallyManaged) {
+            if (envType === 'conda') {
+                return `conda install -n ${envName || 'base'} ipykernel`;
+            }
+            if (envType === 'pixi') {
+                return `pixi add ipykernel`;
+            }
+            // venv / pyenv / plain: pip into the interpreter directly.
+            return `${py} -m pip install ipykernel`;
+        }
+        // Externally managed (PEP 668): can't install in place — create an isolated
+        // env Nebula will then discover under ~/.venvs.
+        if (envType === 'uv') {
+            return `uv venv ~/.venvs/nebula && uv pip install --python ~/.venvs/nebula/bin/python ipykernel`;
+        }
+        return `${py} -m venv ~/.venvs/nebula && ~/.venvs/nebula/bin/python -m pip install ipykernel`;
+    }
+    /**
+     * Find conda environments
+     */
+    async findCondaEnvs() {
+        const envs = [];
+        const seenPaths = new Set();
+        // Possible conda executable paths
+        const condaPaths = [
+            '/opt/anaconda3/bin/conda',
+            '/opt/miniconda3/bin/conda',
+            '/opt/homebrew/bin/conda',
+            '/opt/homebrew/anaconda3/bin/conda',
+            path.join(os.homedir(), 'anaconda3', 'bin', 'conda'),
+            path.join(os.homedir(), 'miniconda3', 'bin', 'conda'),
+            path.join(os.homedir(), 'miniforge3', 'bin', 'conda'),
+            path.join(os.homedir(), 'mambaforge', 'bin', 'conda'),
+            '/usr/local/anaconda3/bin/conda',
+            '/usr/local/miniconda3/bin/conda',
+        ];
+        // Try to get envs from conda command
+        for (const condaPath of condaPaths) {
+            if (!fs.existsSync(condaPath))
+                continue;
+            try {
+                const { stdout } = await this.runCommand(condaPath, ['env', 'list', '--json'], this.condaListTimeoutMs);
+                const data = JSON.parse(stdout);
+                for (const envPath of data.envs || []) {
+                    const pythonPath = path.join(envPath, 'bin', 'python');
+                    if (fs.existsSync(pythonPath) && !seenPaths.has(pythonPath)) {
+                        seenPaths.add(pythonPath);
+                        const envName = path.basename(envPath);
+                        const isBase = envPath === data.root_prefix || !envPath.includes('envs');
+                        envs.push({
+                            path: pythonPath,
+                            envType: 'conda',
+                            envName: isBase ? 'base' : envName,
+                            base: envPath,
+                        });
+                    }
+                }
+            }
+            catch (e) {
+                console.warn(`Error running conda env list: ${e}`);
+            }
+        }
+        // Also scan common conda base directories
+        for (const base of this.getCondaBasePaths()) {
+            if (!fs.existsSync(base))
+                continue;
+            // Base environment
+            const basePython = path.join(base, 'bin', 'python');
+            if (fs.existsSync(basePython) && !seenPaths.has(basePython)) {
+                seenPaths.add(basePython);
+                envs.push({
+                    path: basePython,
+                    envType: 'conda',
+                    envName: 'base',
+                    base,
+                });
+            }
+            // Sub-environments
+            const envsDir = path.join(base, 'envs');
+            if (fs.existsSync(envsDir)) {
+                try {
+                    for (const envDir of fs.readdirSync(envsDir)) {
+                        const envPath = path.join(envsDir, envDir);
+                        if (!fs.statSync(envPath).isDirectory())
+                            continue;
+                        const pythonPath = path.join(envPath, 'bin', 'python');
+                        if (fs.existsSync(pythonPath) && !seenPaths.has(pythonPath)) {
+                            seenPaths.add(pythonPath);
+                            envs.push({
+                                path: pythonPath,
+                                envType: 'conda',
+                                envName: envDir,
+                                base,
+                            });
+                        }
+                    }
+                }
+                catch (e) {
+                    console.warn(`Error scanning conda envs: ${e}`);
+                }
+            }
+        }
+        return envs;
+    }
+    /**
+     * Find pyenv Python versions
+     */
+    findPyenvVersions() {
+        const envs = [];
+        const pyenvRoot = this.getPyenvVersionsPath();
+        if (!fs.existsSync(pyenvRoot)) {
+            return envs;
+        }
+        try {
+            for (const versionDir of fs.readdirSync(pyenvRoot)) {
+                const versionPath = path.join(pyenvRoot, versionDir);
+                if (!fs.statSync(versionPath).isDirectory())
+                    continue;
+                const pythonPath = path.join(versionPath, 'bin', 'python');
+                if (fs.existsSync(pythonPath)) {
+                    envs.push({
+                        path: pythonPath,
+                        envType: 'pyenv',
+                        envName: versionDir,
+                    });
+                }
+            }
+        }
+        catch (e) {
+            console.warn(`Error scanning pyenv versions: ${e}`);
+        }
+        return envs;
+    }
+    /**
+     * Find virtualenvs in common locations
+     */
+    findVirtualenvs() {
+        const envs = [];
+        for (const venvDir of this.getVirtualenvPaths()) {
+            if (!fs.existsSync(venvDir))
+                continue;
+            try {
+                for (const envName of fs.readdirSync(venvDir)) {
+                    const envPath = path.join(venvDir, envName);
+                    if (!fs.statSync(envPath).isDirectory())
+                        continue;
+                    const pythonPath = path.join(envPath, 'bin', 'python');
+                    if (fs.existsSync(pythonPath)) {
+                        envs.push({
+                            path: pythonPath,
+                            envType: 'venv',
+                            envName,
+                        });
+                    }
+                }
+            }
+            catch (e) {
+                console.warn(`Error scanning virtualenvs: ${e}`);
+            }
+        }
+        return envs;
+    }
+    /**
+     * Find system Python installations
+     */
+    findSystemPythons() {
+        const envs = [];
+        const seen = new Set();
+        for (const pythonPath of this.getSystemPythonPaths()) {
+            if (!fs.existsSync(pythonPath))
+                continue;
+            // Resolve symlinks to avoid duplicates
+            try {
+                const realPath = fs.realpathSync(pythonPath);
+                if (seen.has(realPath))
+                    continue;
+                seen.add(realPath);
+            }
+            catch {
+                continue;
+            }
+            const envType = pythonPath.toLowerCase().includes('homebrew') ||
+                pythonPath.includes('/opt/homebrew') ? 'homebrew' : 'system';
+            envs.push({
+                path: pythonPath,
+                envType,
+                envName: null,
+            });
+        }
+        return envs;
+    }
+    /**
+     * Enrich a candidate with version and ipykernel info
+     */
+    async enrichEnvironment(candidate) {
+        const version = await this.getPythonVersion(candidate.path);
+        if (!version) {
+            return null;
+        }
+        const { hasIpykernel, externallyManaged, isVenv } = await this.probeEnvironment(candidate.path);
+        // Refine the type via stable path markers (uv/pixi) that the coarse scans
+        // can't distinguish; resolve symlinks first (e.g. ~/.local/bin/python3 → uv).
+        let realPath = candidate.path;
+        try {
+            realPath = fs.realpathSync(candidate.path);
+        }
+        catch { /* keep original */ }
+        const envType = this.classifyEnvType(candidate.path, realPath, candidate.envType, isVenv);
+        const displayName = this.generateDisplayName(version, envType, candidate.envName);
+        const installHint = this.buildInstallHint(candidate.path, envType, candidate.envName, hasIpykernel, externallyManaged);
+        return {
+            path: candidate.path,
+            version,
+            displayName,
+            envType,
+            envName: candidate.envName,
+            hasIpykernel,
+            kernelName: null,
+            externallyManaged,
+            installHint,
+        };
+    }
+    /**
+     * Perform the actual discovery (internal, always runs full scan)
+     */
+    async performDiscovery() {
+        console.log('Discovering Python environments...');
+        // Collect all candidates
+        const candidates = [];
+        candidates.push(...(await this.findCondaEnvs()));
+        candidates.push(...this.findPyenvVersions());
+        candidates.push(...this.findVirtualenvs());
+        candidates.push(...this.findSystemPythons());
+        // Enrich in parallel
+        const enrichPromises = candidates.map(c => this.enrichEnvironment(c));
+        const results = await Promise.all(enrichPromises);
+        const environments = results.filter((e) => e !== null);
+        // Sort and cache
+        const sorted = this.sortEnvironments(environments);
+        // Save to cache
+        const cacheMap = {};
+        for (const env of sorted) {
+            cacheMap[env.path] = env;
+        }
+        this.saveToCache(cacheMap);
+        console.log(`Discovered ${sorted.length} Python environments`);
+        return sorted;
+    }
+    /**
+     * Trigger background refresh (non-blocking)
+     */
+    triggerBackgroundRefresh() {
+        if (this.backgroundRefreshInProgress) {
+            return; // Already refreshing
+        }
+        this.backgroundRefreshInProgress = true;
+        console.log('Starting background Python environment refresh...');
+        // Run discovery in background, don't await
+        this.performDiscovery()
+            .then(() => {
+            console.log('Background Python environment refresh complete');
+        })
+            .catch((e) => {
+            console.warn('Background Python environment refresh failed:', e);
+        })
+            .finally(() => {
+            this.backgroundRefreshInProgress = false;
+        });
+    }
+    /**
+     * Discover all Python environments
+     *
+     * Uses stale-while-revalidate pattern:
+     * - If cache exists (even stale): return immediately, refresh in background if stale
+     * - If no cache: block and perform full discovery
+     * - If forceRefresh: block and perform full discovery
+     */
+    async discover(options = {}) {
+        const { forceRefresh = false } = options;
+        // Force refresh: always block and run full discovery
+        if (forceRefresh) {
+            return this.performDiscovery();
+        }
+        // Cache valid: return immediately
+        if (this.isCacheValid()) {
+            return this.sortEnvironments(Object.values(this.cache));
+        }
+        // Cache exists but stale: return stale cache, refresh in background
+        const cachedEnvs = this.getFromCache();
+        if (cachedEnvs) {
+            this.triggerBackgroundRefresh();
+            return this.sortEnvironments(Object.values(cachedEnvs));
+        }
+        // No cache at all: must block and discover
+        return this.performDiscovery();
+    }
+    /**
+     * Check if background refresh is in progress
+     */
+    isRefreshing() {
+        return this.backgroundRefreshInProgress;
+    }
+    /**
+     * Register a Python environment as a Jupyter kernel.
+     *
+     * Policy (capability-based, see ADR in the kernel onboarding flow):
+     *   - If `ipykernel` is already importable → just register the kernelspec.
+     *     This is the safe, universal path and works for every ecosystem.
+     *   - If `ipykernel` is missing and the interpreter is PEP 668 externally
+     *     managed → refuse, with a `needs_ipykernel`/`externally_managed` code so
+     *     the UI shows guidance instead of a raw pip traceback. Nebula does not
+     *     install into managed interpreters.
+     *   - If `ipykernel` is missing but the interpreter is writable (a plain venv,
+     *     conda env, …) → install it, then register. This keeps the API usable for
+     *     deliberate callers (MCP, scripts); the UI funnels everything through the
+     *     register-only path.
+     */
+    async installKernel(pythonPath, kernelName) {
+        if (!fs.existsSync(pythonPath)) {
+            throw new types_1.KernelProvisionError(`Python not found: ${pythonPath}`, 'python_not_found');
+        }
+        const { hasIpykernel, externallyManaged } = await this.probeEnvironment(pythonPath);
+        if (!hasIpykernel) {
+            if (externallyManaged) {
+                const version = await this.getPythonVersion(pythonPath);
+                const hint = this.buildInstallHint(pythonPath, 'system', null, false, true);
+                throw new types_1.KernelProvisionError(`This Python (${version || pythonPath}) is externally managed (PEP 668) and ipykernel is not installed, ` +
+                    `so Nebula can't install it here. Set up ipykernel in an isolated environment, then Register it.`, 'externally_managed', hint || undefined);
+            }
+            // Writable env without ipykernel: install it (safe — not externally managed).
+            console.log(`Installing ipykernel for ${pythonPath}...`);
+            try {
+                (0, child_process_1.execSync)(`"${pythonPath}" -m pip install ipykernel -q`, {
+                    timeout: this.kernelInstallTimeoutMs,
+                    stdio: ['pipe', 'pipe', 'pipe'],
+                });
+            }
+            catch (e) {
+                const detail = this.errorOutput(e);
+                // A late-detected PEP 668 (marker absent but pip still refused): treat as managed.
+                if (this.isExternallyManagedError(detail)) {
+                    const hint = this.buildInstallHint(pythonPath, 'system', null, false, true);
+                    throw new types_1.KernelProvisionError(`This Python blocks package installation (PEP 668). Set up ipykernel in an isolated environment, then Register it.`, 'externally_managed', hint || undefined);
+                }
+                throw new types_1.KernelProvisionError(`Failed to install ipykernel: ${detail || e}`, 'install_failed');
+            }
+        }
+        // Generate kernel name if not provided
+        if (!kernelName) {
+            const version = await this.getPythonVersion(pythonPath) || '3';
+            kernelName = this.generateKernelName(pythonPath, version);
+        }
+        // Register kernel
+        console.log(`Registering kernel as ${kernelName}...`);
+        try {
+            (0, child_process_1.execSync)(`"${pythonPath}" -m ipykernel install --user --name "${kernelName}"`, {
+                timeout: this.registrationTimeoutMs,
+                stdio: ['pipe', 'pipe', 'pipe'],
+            });
+        }
+        catch (e) {
+            throw new types_1.KernelProvisionError(`Failed to register kernel: ${this.errorOutput(e) || e}`, 'register_failed');
+        }
+        // Update cache entry
+        if (this.cache[pythonPath]) {
+            this.cache[pythonPath].hasIpykernel = true;
+            this.cache[pythonPath].kernelName = kernelName;
+            this.saveToCache(this.cache);
+        }
+        return {
+            kernelName,
+            pythonPath,
+            message: `Successfully registered kernel '${kernelName}'`,
+        };
+    }
+    /** Extract combined stdout+stderr text from a child_process error. */
+    errorOutput(e) {
+        const err = e;
+        const parts = [err?.stderr, err?.stdout, err?.message]
+            .map(p => (p == null ? '' : p.toString()))
+            .filter(Boolean);
+        return parts.join('\n');
+    }
+    /** Detect PEP 668 "externally managed" refusals generically (not tool-specific). */
+    isExternallyManagedError(msg) {
+        const m = (msg || '').toLowerCase();
+        return m.includes('externally-managed')
+            || m.includes('externally managed')
+            || m.includes('break-system-packages')
+            || m.includes('pep 668');
+    }
+}
+exports.PythonDiscoveryService = PythonDiscoveryService;
+// Global instance with default configuration
+exports.pythonDiscovery = new PythonDiscoveryService();