nebula-notebook 0.1.0

package/node-server/dist/cluster/server-registry.js

@@ -0,0 +1,217 @@
+"use strict";
+/**
+ * Server Registry
+ *
+ * Manages registration of peer servers in a Nebula cluster.
+ * Peer servers can register with a main server to enable
+ * cross-server kernel access.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.serverRegistry = void 0;
+const cluster_secret_1 = require("./cluster-secret");
+const HEARTBEAT_TIMEOUT_MS = 90_000; // 90 seconds (3 missed heartbeats at 30s interval)
+const CLEANUP_INTERVAL_MS = 30_000; // Check for stale servers every 30s
+class ServerRegistry {
+    servers = new Map();
+    clusterSecret = null;
+    cleanupInterval = null;
+    localServerId = 'local';
+    constructor() {
+        // Load initial cluster secret from environment or disk
+        this.clusterSecret = process.env.NEBULA_CLUSTER_SECRET || (0, cluster_secret_1.readClusterSecret)() || null;
+        // Start cleanup interval
+        this.startCleanupInterval();
+    }
+    /**
+     * Set the local server's ID (called on startup)
+     */
+    setLocalServerId(id) {
+        this.localServerId = id;
+    }
+    /**
+     * Get the local server's ID
+     */
+    getLocalServerId() {
+        return this.localServerId;
+    }
+    /**
+     * Validate registration secret
+     */
+    getClusterSecret() {
+        const envSecret = process.env.NEBULA_CLUSTER_SECRET;
+        // If the env var is explicitly set (even to an empty string), treat it as the
+        // source of truth. This allows users/tests to intentionally disable a disk secret
+        // without relying on filesystem state.
+        if (envSecret !== undefined) {
+            this.clusterSecret = envSecret || null;
+            return this.clusterSecret;
+        }
+        // Disk secret is cached defensively: if the file can't be read, don't clear an
+        // existing secret to avoid accidentally dropping auth due to transient errors.
+        const diskSecret = (0, cluster_secret_1.readClusterSecret)() || null;
+        if (diskSecret && diskSecret !== this.clusterSecret) {
+            this.clusterSecret = diskSecret;
+        }
+        return this.clusterSecret;
+    }
+    validateSecret(providedSecret) {
+        const clusterSecret = this.getClusterSecret();
+        // If no cluster secret configured, allow all registrations (dev mode)
+        if (!clusterSecret) {
+            return true;
+        }
+        return providedSecret === clusterSecret;
+    }
+    /**
+     * Generate server ID from host and port
+     */
+    generateServerId(host, port) {
+        return `${host}:${port}`;
+    }
+    /**
+     * Register a peer server
+     */
+    register(request) {
+        // Validate secret
+        if (!this.validateSecret(request.secret)) {
+            return { success: false, error: 'Invalid cluster secret' };
+        }
+        const serverId = this.generateServerId(request.host, request.port);
+        const now = Date.now();
+        // Check if already registered
+        const existing = this.servers.get(serverId);
+        if (existing) {
+            // Update existing registration
+            existing.lastHeartbeat = now;
+            existing.status = 'online';
+            existing.name = request.name || existing.name;
+            if (request.resources) {
+                existing.resources = request.resources;
+            }
+            console.log(`[ServerRegistry] Updated registration for ${serverId}`);
+            return { success: true, serverId };
+        }
+        // New registration
+        const server = {
+            id: serverId,
+            host: request.host,
+            port: request.port,
+            name: request.name,
+            url: `http://${request.host}:${request.port}`,
+            registeredAt: now,
+            lastHeartbeat: now,
+            status: 'online',
+            resources: request.resources,
+        };
+        this.servers.set(serverId, server);
+        console.log(`[ServerRegistry] Registered new server: ${serverId} (${request.name || 'unnamed'})`);
+        return { success: true, serverId };
+    }
+    /**
+     * Unregister a peer server
+     */
+    unregister(serverId) {
+        const removed = this.servers.delete(serverId);
+        if (removed) {
+            console.log(`[ServerRegistry] Unregistered server: ${serverId}`);
+        }
+        return removed;
+    }
+    /**
+     * Record heartbeat from a peer server
+     */
+    heartbeat(serverId, resources) {
+        const server = this.servers.get(serverId);
+        if (!server) {
+            return false;
+        }
+        server.lastHeartbeat = Date.now();
+        server.status = 'online';
+        if (resources) {
+            server.resources = resources;
+        }
+        return true;
+    }
+    /**
+     * Get a specific peer server
+     */
+    getServer(serverId) {
+        return this.servers.get(serverId);
+    }
+    /**
+     * Get all registered peer servers
+     */
+    getAllServers() {
+        return Array.from(this.servers.values());
+    }
+    /**
+     * Get all online peer servers
+     */
+    getOnlineServers() {
+        return this.getAllServers().filter(s => s.status === 'online');
+    }
+    /**
+     * Check server health and update status
+     */
+    checkServerHealth() {
+        const now = Date.now();
+        for (const server of this.servers.values()) {
+            if (now - server.lastHeartbeat > HEARTBEAT_TIMEOUT_MS) {
+                if (server.status === 'online') {
+                    console.log(`[ServerRegistry] Server ${server.id} marked offline (heartbeat timeout)`);
+                    server.status = 'offline';
+                }
+            }
+        }
+    }
+    /**
+     * Start the cleanup interval
+     */
+    startCleanupInterval() {
+        if (this.cleanupInterval) {
+            clearInterval(this.cleanupInterval);
+        }
+        this.cleanupInterval = setInterval(() => {
+            this.checkServerHealth();
+        }, CLEANUP_INTERVAL_MS);
+    }
+    /**
+     * Stop the cleanup interval (for shutdown)
+     */
+    shutdown() {
+        if (this.cleanupInterval) {
+            clearInterval(this.cleanupInterval);
+            this.cleanupInterval = null;
+        }
+    }
+    /**
+     * Get cluster info for API response
+     */
+    getClusterInfo(localResources) {
+        const servers = this.getAllServers().map(s => ({
+            id: s.id,
+            name: s.name,
+            url: s.url,
+            status: s.status,
+            isLocal: false,
+            resources: s.resources,
+        }));
+        // Add local server at the beginning
+        servers.unshift({
+            id: this.localServerId,
+            name: 'Local',
+            url: '', // Local doesn't need URL
+            status: 'online',
+            isLocal: true,
+            resources: localResources,
+        });
+        return {
+            localServerId: this.localServerId,
+            peerCount: this.servers.size,
+            onlineCount: this.getOnlineServers().length,
+            servers,
+        };
+    }
+}
+// Global singleton
+exports.serverRegistry = new ServerRegistry();

package/node-server/dist/config/output-limits.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Kernel output buffer limits (keep in sync with frontend display.config.ts)
+ */
+export declare const MAX_OUTPUT_LINES = 10000;
+export declare const MAX_OUTPUT_CHARS = 100000000;
+export declare const MAX_OUTPUT_LINES_ERROR = 10000;
+export declare const MAX_OUTPUT_CHARS_ERROR = 100000000;

package/node-server/dist/config/output-limits.js

@@ -0,0 +1,10 @@
+"use strict";
+/**
+ * Kernel output buffer limits (keep in sync with frontend display.config.ts)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_OUTPUT_CHARS_ERROR = exports.MAX_OUTPUT_LINES_ERROR = exports.MAX_OUTPUT_CHARS = exports.MAX_OUTPUT_LINES = void 0;
+exports.MAX_OUTPUT_LINES = 10000;
+exports.MAX_OUTPUT_CHARS = 100_000_000;
+exports.MAX_OUTPUT_LINES_ERROR = 10000;
+exports.MAX_OUTPUT_CHARS_ERROR = 100_000_000;

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

@@ -0,0 +1,198 @@
+/**
+ * Python Discovery Service
+ *
+ * Discovers Python environments on the system (conda, pyenv, venv, system).
+ * Node.js port of the Python PythonDiscoveryService.
+ */
+import { PythonEnvironment, PythonEnvType, CacheInfo, InstallKernelResult } from './types';
+export interface DiscoveryServiceOptions {
+    cacheFile?: string;
+    cacheTtlHours?: number;
+    versionCheckTimeoutMs?: number;
+    ipykernelCheckTimeoutMs?: number;
+    condaListTimeoutMs?: number;
+    kernelInstallTimeoutMs?: number;
+    registrationTimeoutMs?: number;
+}
+export declare class PythonDiscoveryService {
+    private cache;
+    private cacheTimestamp;
+    private cacheFile;
+    private cacheTtlHours;
+    private versionCheckTimeoutMs;
+    private ipykernelCheckTimeoutMs;
+    private condaListTimeoutMs;
+    private kernelInstallTimeoutMs;
+    private registrationTimeoutMs;
+    private backgroundRefreshInProgress;
+    constructor(options?: DiscoveryServiceOptions);
+    /**
+     * Load cache from disk
+     */
+    private loadCache;
+    /**
+     * Save environments to cache
+     */
+    saveToCache(environments: Record<string, PythonEnvironment>): void;
+    /**
+     * Get environments from cache (returns null if empty)
+     */
+    getFromCache(): Record<string, PythonEnvironment> | null;
+    /**
+     * Check if cache is still valid
+     */
+    isCacheValid(): boolean;
+    /**
+     * Get cache info
+     */
+    getCacheInfo(): CacheInfo & {
+        refreshing: boolean;
+    };
+    /**
+     * Run a command asynchronously with timeout
+     */
+    private runCommand;
+    /**
+     * Generate display name for an environment
+     */
+    generateDisplayName(version: string, envType: PythonEnvType, envName: string | null): string;
+    /**
+     * Sort environments by type priority and name
+     */
+    sortEnvironments(envs: PythonEnvironment[]): PythonEnvironment[];
+    /**
+     * Check if a python path exists
+     */
+    pythonExists(pythonPath: string): boolean;
+    /**
+     * Get common conda base paths to search
+     */
+    getCondaBasePaths(): string[];
+    /**
+     * Get common system python paths
+     */
+    getSystemPythonPaths(): string[];
+    /**
+     * Get pyenv versions path
+     */
+    getPyenvVersionsPath(): string;
+    /**
+     * Get common virtualenv paths
+     */
+    getVirtualenvPaths(): string[];
+    /**
+     * Generate a unique kernel name from path
+     */
+    generateKernelName(pythonPath: string, version: string): string;
+    /**
+     * Simple string hash function
+     */
+    private hashString;
+    /**
+     * Parse Python version from version string
+     */
+    parseVersionString(versionOutput: string): string;
+    /**
+     * Get Python version from executable
+     */
+    private getPythonVersion;
+    /**
+     * Check if ipykernel is installed
+     */
+    private checkIpykernel;
+    /**
+     * 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.
+     */
+    private probeEnvironment;
+    /**
+     * 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".
+     */
+    private classifyEnvType;
+    /**
+     * 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).
+     */
+    private buildInstallHint;
+    /**
+     * Find conda environments
+     */
+    private findCondaEnvs;
+    /**
+     * Find pyenv Python versions
+     */
+    private findPyenvVersions;
+    /**
+     * Find virtualenvs in common locations
+     */
+    private findVirtualenvs;
+    /**
+     * Find system Python installations
+     */
+    private findSystemPythons;
+    /**
+     * Enrich a candidate with version and ipykernel info
+     */
+    private enrichEnvironment;
+    /**
+     * Perform the actual discovery (internal, always runs full scan)
+     */
+    private performDiscovery;
+    /**
+     * Trigger background refresh (non-blocking)
+     */
+    private triggerBackgroundRefresh;
+    /**
+     * 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
+     */
+    discover(options?: {
+        forceRefresh?: boolean;
+    }): Promise<PythonEnvironment[]>;
+    /**
+     * Check if background refresh is in progress
+     */
+    isRefreshing(): boolean;
+    /**
+     * 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.
+     */
+    installKernel(pythonPath: string, kernelName?: string): Promise<InstallKernelResult>;
+    /** Extract combined stdout+stderr text from a child_process error. */
+    private errorOutput;
+    /** Detect PEP 668 "externally managed" refusals generically (not tool-specific). */
+    private isExternallyManagedError;
+}
+export declare const pythonDiscovery: PythonDiscoveryService;