nebula-notebook 0.2.0 → 0.2.1

package/node-server/dist/discovery/conda-locations.js

@@ -0,0 +1,427 @@
+"use strict";
+/**
+ * Conda Location Discovery (VSCode/PET-style filesystem forensics)
+ *
+ * Finds conda installs and environments WITHOUT executing conda/mamba —
+ * spawning conda boots a full Python interpreter and takes seconds, and the
+ * binary may not even be on PATH for envs created by mamba/micromamba or
+ * from another shell. Instead, everything comes from files conda itself
+ * maintains:
+ *
+ *   - ~/.conda/environments.txt — conda appends EVERY env it creates here
+ *     (named, path-based `-p` envs, and base), so this single file covers
+ *     envs living in arbitrary locations.
+ *   - .condarc `envs_dirs`/`envs_path` — user-configured env containers.
+ *   - Well-known install roots (~/miniconda3, /opt/homebrew/…, micromamba…).
+ *   - CONDA_* / MAMBA_* environment variables.
+ *   - conda/mamba/micromamba binaries on PATH — the install root is derived
+ *     from the (symlink-resolved) binary location, never by running it.
+ *
+ * A directory IS a conda env iff it has a `conda-meta/` directory (pixi envs
+ * carry a `conda-meta/pixi` marker and are excluded — the pixi locator owns
+ * those). An env is an install root iff it also has `envs/` or `condabin/`.
+ */
+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.defaultCondaContext = defaultCondaContext;
+exports.isCondaEnv = isCondaEnv;
+exports.isCondaInstall = isCondaInstall;
+exports.readEnvironmentsTxt = readEnvironmentsTxt;
+exports.parseCondaRcEnvDirs = parseCondaRcEnvDirs;
+exports.getCondaRcSearchPaths = getCondaRcSearchPaths;
+exports.getCondaRcEnvDirs = getCondaRcEnvDirs;
+exports.getKnownCondaRoots = getKnownCondaRoots;
+exports.getCondaRootsFromPath = getCondaRootsFromPath;
+exports.findCondaLikeBinaries = findCondaLikeBinaries;
+exports.pythonExeForPrefix = pythonExeForPrefix;
+exports.prefixForPythonExe = prefixForPythonExe;
+exports.findExecutableOnPath = findExecutableOnPath;
+exports.collectCondaEnvs = collectCondaEnvs;
+const fs_1 = require("fs");
+const path = __importStar(require("path"));
+const os = __importStar(require("os"));
+function defaultCondaContext() {
+    return { home: os.homedir(), env: process.env, platform: process.platform };
+}
+async function isDir(p) {
+    try {
+        return (await fs_1.promises.stat(p)).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+async function isFile(p) {
+    try {
+        return (await fs_1.promises.stat(p)).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+/** conda-meta/ present, and not a pixi env (conda-meta/pixi marker). */
+async function isCondaEnv(dir) {
+    if (!(await isDir(path.join(dir, 'conda-meta'))))
+        return false;
+    return !(await isFile(path.join(dir, 'conda-meta', 'pixi')));
+}
+/** An install root is itself an env (base) that also carries envs/ or condabin/. */
+async function isCondaInstall(dir) {
+    if (!(await isCondaEnv(dir)))
+        return false;
+    return (await isDir(path.join(dir, 'envs'))) || (await isDir(path.join(dir, 'condabin')));
+}
+/** Env prefixes recorded by conda itself — one absolute path per line. */
+async function readEnvironmentsTxt(ctx) {
+    const file = path.join(ctx.home, '.conda', 'environments.txt');
+    let content;
+    try {
+        content = await fs_1.promises.readFile(file, 'utf-8');
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const rawLine of content.split(/\r?\n/)) {
+        const line = rawLine.trim();
+        if (!line || line.startsWith('#'))
+            continue;
+        if (await isCondaEnv(line))
+            out.push(line);
+    }
+    return out;
+}
+function expandUser(p, home) {
+    if (p === '~')
+        return home;
+    if (p.startsWith('~/') || p.startsWith('~\\'))
+        return path.join(home, p.slice(2));
+    return p;
+}
+/** Strip surrounding quotes and trailing `  # comment` from a YAML scalar. */
+function cleanYamlScalar(raw, home) {
+    let v = raw.replace(/\s+#.*$/, '').trim();
+    if ((v.startsWith('"') && v.endsWith('"')) || (v.startsWith("'") && v.endsWith("'"))) {
+        v = v.slice(1, -1);
+    }
+    if (!v)
+        return null;
+    return expandUser(v, home);
+}
+/**
+ * Minimal .condarc reader for the two keys that name env containers.
+ * Handles block lists and inline `[a, b]` lists; deliberately not a full
+ * YAML parser — these files are flat and hand-written.
+ */
+function parseCondaRcEnvDirs(content, home) {
+    const dirs = [];
+    const lines = content.split(/\r?\n/);
+    for (let i = 0; i < lines.length; i++) {
+        const m = lines[i].match(/^(envs_dirs|envs_path)\s*:\s*(.*)$/);
+        if (!m)
+            continue;
+        const rest = m[2].trim();
+        if (rest.startsWith('[')) {
+            for (const part of rest.replace(/^\[|\]\s*$/g, '').split(',')) {
+                const v = cleanYamlScalar(part, home);
+                if (v)
+                    dirs.push(v);
+            }
+            continue;
+        }
+        // Block list: consume `- item` lines (comments/blanks allowed between)
+        for (let j = i + 1; j < lines.length; j++) {
+            const line = lines[j];
+            if (/^\s*(#.*)?$/.test(line))
+                continue; // blank or comment
+            const item = line.match(/^\s+-\s+(.*)$/);
+            if (!item)
+                break; // next top-level key
+            const v = cleanYamlScalar(item[1], home);
+            if (v)
+                dirs.push(v);
+        }
+    }
+    return dirs;
+}
+/** Every .condarc-style file worth checking, most specific first. */
+function getCondaRcSearchPaths(ctx) {
+    const { home, env } = ctx;
+    const paths = [];
+    if (env.CONDARC)
+        paths.push(env.CONDARC);
+    if (env.MAMBARC)
+        paths.push(env.MAMBARC);
+    for (const root of [env.CONDA_PREFIX, env.CONDA_ROOT].filter(Boolean)) {
+        paths.push(path.join(root, '.condarc'));
+    }
+    const xdg = env.XDG_CONFIG_HOME;
+    if (xdg)
+        paths.push(path.join(xdg, 'conda', '.condarc'));
+    paths.push(path.join(home, '.config', 'conda', '.condarc'), path.join(home, '.conda', '.condarc'), path.join(home, '.condarc'), path.join(home, '.mambarc'), '/etc/conda/.condarc', '/var/lib/conda/.condarc');
+    return paths;
+}
+/** Env container dirs from every .condarc found (envs_dirs / envs_path). */
+async function getCondaRcEnvDirs(ctx) {
+    const dirs = [];
+    for (const rc of getCondaRcSearchPaths(ctx)) {
+        try {
+            const content = await fs_1.promises.readFile(rc, 'utf-8');
+            dirs.push(...parseCondaRcEnvDirs(content, ctx.home));
+        }
+        catch { /* missing/unreadable rc — skip */ }
+    }
+    return [...new Set(dirs)];
+}
+const INSTALL_DIR_NAMES = [
+    'anaconda', 'anaconda3',
+    'miniconda', 'miniconda3',
+    'miniforge', 'miniforge3',
+    'mambaforge', 'micromamba',
+];
+/** Well-known install roots (cheap string candidates; existence checked later). */
+function getKnownCondaRoots(ctx) {
+    const { home, env, platform } = ctx;
+    const roots = [];
+    for (const v of [env.CONDA_ROOT, env.CONDA_PREFIX, env.MAMBA_ROOT_PREFIX, env.CONDA_DIR, env.CONDA]) {
+        if (v)
+            roots.push(expandUser(v, home));
+    }
+    const prefixes = [
+        home,
+        path.join(home, 'opt'),
+        path.join(home, '.conda'),
+        path.join(home, '.local'),
+        '/opt', '/usr/share', '/usr/local', '/usr',
+    ];
+    if (platform === 'darwin')
+        prefixes.push('/opt/homebrew');
+    if (platform === 'linux')
+        prefixes.push('/home/linuxbrew/.linuxbrew');
+    for (const prefix of prefixes) {
+        for (const name of INSTALL_DIR_NAMES) {
+            roots.push(path.join(prefix, name));
+        }
+    }
+    roots.push('/opt/conda', '/anaconda', '/anaconda3', '/miniconda', '/miniconda3', '/miniforge3', '/micromamba');
+    return [...new Set(roots)];
+}
+const CONDA_BINARY_NAMES = ['conda', 'mamba', 'micromamba'];
+function pathEntries(ctx) {
+    const sep = ctx.platform === 'win32' ? ';' : ':';
+    return (ctx.env.PATH || '').split(sep).filter(Boolean);
+}
+function binaryCandidates(dir, name, platform) {
+    if (platform === 'win32') {
+        return [path.join(dir, `${name}.exe`), path.join(dir, `${name}.bat`)];
+    }
+    return [path.join(dir, name)];
+}
+/**
+ * Derive install roots from conda-like binaries on PATH: resolve the symlink
+ * (homebrew shims point into Caskroom), then walk out of bin/condabin/Scripts.
+ * The binary is never executed.
+ */
+async function getCondaRootsFromPath(ctx) {
+    const roots = [];
+    for (const dir of pathEntries(ctx)) {
+        for (const name of CONDA_BINARY_NAMES) {
+            for (const exe of binaryCandidates(dir, name, ctx.platform)) {
+                if (!(await isFile(exe)))
+                    continue;
+                let real = exe;
+                try {
+                    real = await fs_1.promises.realpath(exe);
+                }
+                catch { /* keep original */ }
+                const parent = path.dirname(real);
+                const candidate = ['bin', 'condabin', 'Scripts'].includes(path.basename(parent).toLowerCase())
+                    ? path.dirname(parent)
+                    : parent;
+                if (await isCondaEnv(candidate))
+                    roots.push(candidate);
+            }
+        }
+    }
+    return [...new Set(roots)];
+}
+/**
+ * Locate conda/mamba/micromamba binaries (PATH first, then known roots) for
+ * callers that DO need to run conda — e.g. `conda install -p <prefix>` in the
+ * ipykernel install flow. Discovery itself never executes these.
+ */
+async function findCondaLikeBinaries(ctx = defaultCondaContext()) {
+    const found = [];
+    const seen = new Set();
+    const add = async (exe) => {
+        if (!(await isFile(exe)))
+            return;
+        let real = exe;
+        try {
+            real = await fs_1.promises.realpath(exe);
+        }
+        catch { /* keep original */ }
+        if (seen.has(real))
+            return;
+        seen.add(real);
+        found.push(exe);
+    };
+    for (const dir of pathEntries(ctx)) {
+        for (const name of CONDA_BINARY_NAMES) {
+            for (const exe of binaryCandidates(dir, name, ctx.platform))
+                await add(exe);
+        }
+    }
+    const binDirs = ctx.platform === 'win32' ? ['Scripts', 'condabin'] : ['bin', 'condabin'];
+    for (const root of [...getKnownCondaRoots(ctx), ...(await getCondaRootsFromPath(ctx))]) {
+        for (const sub of binDirs) {
+            for (const name of CONDA_BINARY_NAMES) {
+                for (const exe of binaryCandidates(path.join(root, sub), name, ctx.platform))
+                    await add(exe);
+            }
+        }
+    }
+    return found;
+}
+function pythonExeForPrefix(prefix, platform) {
+    return platform === 'win32'
+        ? path.win32.join(prefix, 'python.exe')
+        : path.join(prefix, 'bin', 'python');
+}
+/** Inverse of pythonExeForPrefix: the env prefix a python executable lives in. */
+function prefixForPythonExe(pythonPath) {
+    const parent = path.dirname(pythonPath);
+    return ['bin', 'scripts'].includes(path.basename(parent).toLowerCase())
+        ? path.dirname(parent)
+        : parent;
+}
+/** First match for an executable name on the context's PATH (fs check only). */
+async function findExecutableOnPath(name, ctx = defaultCondaContext()) {
+    for (const dir of pathEntries(ctx)) {
+        for (const exe of binaryCandidates(dir, name, ctx.platform)) {
+            if (await isFile(exe))
+                return exe;
+        }
+    }
+    return null;
+}
+/**
+ * Name an env prefix the way conda users know it: install roots are 'base',
+ * children of an install's envs/ keep their dirname (and remember the owning
+ * install), and path-based `-p` envs fall back to their basename as a display
+ * label (activation-by-name doesn't apply — Nebula execs the python binary).
+ */
+async function locate(prefix) {
+    if (await isCondaInstall(prefix)) {
+        return { prefix, envName: 'base', base: prefix };
+    }
+    const parent = path.dirname(prefix);
+    const grandparent = path.dirname(parent);
+    if (path.basename(parent) === 'envs' && (await isCondaInstall(grandparent))) {
+        return { prefix, envName: path.basename(prefix), base: grandparent };
+    }
+    return { prefix, envName: path.basename(prefix) };
+}
+/**
+ * The full sweep: merge every source, expand install roots and containers,
+ * and return deduped env locations.
+ */
+async function collectCondaEnvs(ctx = defaultCondaContext()) {
+    const byPrefix = new Map();
+    const add = async (prefix) => {
+        // realpath so the same env reached via different spellings (symlinked
+        // /var vs /private/var, shim dirs, …) dedupes to one entry.
+        let norm;
+        try {
+            norm = await fs_1.promises.realpath(prefix);
+        }
+        catch {
+            return;
+        }
+        if (byPrefix.has(norm))
+            return;
+        if (!(await isCondaEnv(norm)))
+            return;
+        byPrefix.set(norm, await locate(norm));
+    };
+    // 1. environments.txt — the authoritative record, catches arbitrary -p envs.
+    //    If an entry sits under <root>/envs, surface the root's base env too
+    //    (Caskroom-style installs are often only reachable this way).
+    for (const prefix of await readEnvironmentsTxt(ctx)) {
+        await add(prefix);
+        const parent = path.dirname(prefix);
+        if (path.basename(parent) === 'envs') {
+            await add(path.dirname(parent));
+        }
+    }
+    // 2. Install roots: well-known locations + roots derived from PATH binaries.
+    const roots = [...getKnownCondaRoots(ctx), ...(await getCondaRootsFromPath(ctx))];
+    const containers = [];
+    for (const root of roots) {
+        if (await isCondaInstall(root)) {
+            await add(root);
+            containers.push(path.join(root, 'envs'));
+            // Per-install .condarc can add more env containers
+            try {
+                const rc = await fs_1.promises.readFile(path.join(root, '.condarc'), 'utf-8');
+                containers.push(...parseCondaRcEnvDirs(rc, ctx.home));
+            }
+            catch { /* no per-install rc */ }
+        }
+        else if (await isCondaEnv(root)) {
+            await add(root);
+        }
+    }
+    // 3. Env containers: ~/.conda/envs, $CONDA_ENVS_PATH entries, .condarc envs_dirs.
+    containers.push(path.join(ctx.home, '.conda', 'envs'));
+    const envsPathSep = ctx.platform === 'win32' ? ';' : ':';
+    for (const entry of (ctx.env.CONDA_ENVS_PATH || '').split(envsPathSep).filter(Boolean)) {
+        containers.push(expandUser(entry, ctx.home));
+    }
+    containers.push(...(await getCondaRcEnvDirs(ctx)));
+    for (const container of [...new Set(containers)]) {
+        let entries;
+        try {
+            entries = await fs_1.promises.readdir(container);
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            await add(path.join(container, entry));
+        }
+    }
+    return [...byPrefix.values()];
+}

package/node-server/dist/discovery/discovery-service.d.ts

@@ -5,14 +5,25 @@
  * Node.js port of the Python PythonDiscoveryService.
  */
 import { PythonEnvironment, PythonEnvType, CacheInfo, InstallKernelResult } from './types';
+import { CondaLocatorContext } from './conda-locations';
 export interface DiscoveryServiceOptions {
     cacheFile?: string;
     cacheTtlHours?: number;
     versionCheckTimeoutMs?: number;
     ipykernelCheckTimeoutMs?: number;
-    condaListTimeoutMs?: number;
     kernelInstallTimeoutMs?: number;
     registrationTimeoutMs?: number;
+    /** Test seam: override home dir / env vars for the conda locator. */
+    condaLocator?: {
+        home?: string;
+        env?: Record<string, string | undefined>;
+    };
+    /**
+     * Test seam: conda-binary lookup for the install planner. The default
+     * (findCondaLikeBinaries) scans absolute well-known roots too, so a CI
+     * runner's system conda (/usr/share/miniconda) would leak into fixtures.
+     */
+    condaBinaryFinder?: (ctx: CondaLocatorContext) => Promise<string[]>;
 }
 export declare class PythonDiscoveryService {
     private cache;
@@ -21,11 +32,14 @@ export declare class PythonDiscoveryService {
     private cacheTtlHours;
     private versionCheckTimeoutMs;
     private ipykernelCheckTimeoutMs;
-    private condaListTimeoutMs;
     private kernelInstallTimeoutMs;
     private registrationTimeoutMs;
+    private condaLocatorOverrides;
+    private condaBinaryFinder;
     private backgroundRefreshInProgress;
     constructor(options?: DiscoveryServiceOptions);
+    /** Context for the filesystem conda locator (test seam applied). */
+    condaContext(): CondaLocatorContext;
     /**
      * Load cache from disk
      */
@@ -49,7 +63,9 @@ export declare class PythonDiscoveryService {
         refreshing: boolean;
     };
     /**
-     * Run a command asynchronously with timeout
+     * Run a command asynchronously with timeout. `onData` receives every
+     * stdout/stderr chunk as it arrives (interleaved), for callers that
+     * surface live progress (the ipykernel install modal).
      */
     private runCommand;
     /**
@@ -64,6 +80,13 @@ export declare class PythonDiscoveryService {
      * Check if a python path exists
      */
     pythonExists(pythonPath: string): boolean;
+    /**
+     * Async existence check. The discovery scan MUST use this (not existsSync):
+     * env dirs often live on network filesystems (GPFS) where each sync stat can
+     * take 10-500ms, and the scan runs dozens — enough to freeze the entire
+     * event loop for seconds (observed as "terminal dead during autosave").
+     */
+    private fsExists;
     /**
      * Get common conda base paths to search
      */
@@ -132,7 +155,22 @@ export declare class PythonDiscoveryService {
      */
     private buildInstallHint;
     /**
-     * Find conda environments
+     * Public probe for kernel provisioning: does this interpreter have ipykernel,
+     * can we install into it, and if not — what should the user run instead?
+     * Uses the discovery cache for env-type context (better hints) but always
+     * probes the interpreter live, so a just-installed ipykernel is seen
+     * immediately even with a stale cache.
+     */
+    probeForKernel(pythonPath: string): Promise<{
+        hasIpykernel: boolean;
+        externallyManaged: boolean;
+        installHint: string | null;
+    }>;
+    /**
+     * Find conda environments — pure filesystem forensics (see conda-locations.ts).
+     * conda/mamba are never executed: envs come from ~/.conda/environments.txt,
+     * .condarc envs_dirs, well-known roots, the CONDA_ and MAMBA_ env vars, and
+     * roots derived from conda-like binaries found on PATH.
      */
     private findCondaEnvs;
     /**
@@ -190,6 +228,37 @@ export declare class PythonDiscoveryService {
      *     register-only path.
      */
     installKernel(pythonPath: string, kernelName?: string): Promise<InstallKernelResult>;
+    /**
+     * Probe a manually-entered interpreter path, classify it (conda-meta →
+     * conda, pyvenv.cfg → venv, else system + the usual uv/pixi refinement),
+     * and persist it into the discovery cache so it shows up in the picker from
+     * now on. VSCode's "Enter interpreter path…" equivalent.
+     */
+    probeAndRemember(pythonPath: string): Promise<PythonEnvironment>;
+    /**
+     * Pick ONE installer for ipykernel, up front (VSCode's shape — no fallback
+     * chain at run time, so failures are attributable and honest):
+     *   1. conda env → a conda-like binary (conda/mamba/micromamba; PATH first,
+     *      then known roots) with `-p <prefix>` — correct for named, base and
+     *      path-based envs alike.
+     *   2. uv on PATH → `uv pip install --python <exe>` — works on ANY env,
+     *      including conda envs without a conda binary and envs without pip.
+     *   3. the env's own pip.
+     */
+    planIpykernelInstall(pythonPath: string): Promise<{
+        kind: 'conda' | 'uv' | 'pip';
+        argv: string[];
+    }>;
+    /**
+     * Install ipykernel into an environment with the planned installer, then
+     * VERIFY it actually became importable. Refuses PEP 668 externally-managed
+     * interpreters up front (with guidance). Failure carries the installer's
+     * output — no silent fallback to a different installer.
+     */
+    installIpykernel(pythonPath: string, onOutput?: (chunk: string) => void): Promise<{
+        installer: 'none' | 'conda' | 'uv' | 'pip';
+        message: string;
+    }>;
     /** Extract combined stdout+stderr text from a child_process error. */
     private errorOutput;
     /** Detect PEP 668 "externally managed" refusals generically (not tool-specific). */