nebula-notebook 0.1.0

package/node-server/dist/kernel/default-kernel.js

@@ -0,0 +1,138 @@
+"use strict";
+/**
+ * Default kernel resolution based on the Python executable in the server env.
+ */
+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.getDefaultKernelName = getDefaultKernelName;
+exports.invalidateDefaultKernelName = invalidateDefaultKernelName;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const child_process_1 = require("child_process");
+const util_1 = require("util");
+const kernelspec_1 = require("./kernelspec");
+const execFileAsync = (0, util_1.promisify)(child_process_1.execFile);
+let defaultKernelPromise = null;
+let defaultKernelValue = undefined;
+const DEFAULT_PYTHON_COMMANDS = [
+    process.env.PYTHON,
+    'python3',
+    'python',
+].filter(Boolean);
+async function resolveRealPath(filePath) {
+    try {
+        return await fs.promises.realpath(filePath);
+    }
+    catch {
+        return filePath;
+    }
+}
+async function findExecutableOnPath(command, envPath) {
+    if (!envPath)
+        return null;
+    const pathEntries = envPath.split(path.delimiter).filter(Boolean);
+    for (const entry of pathEntries) {
+        const candidate = path.join(entry, command);
+        try {
+            await fs.promises.access(candidate, fs.constants.X_OK);
+            return candidate;
+        }
+        catch {
+            // Keep searching
+        }
+    }
+    return null;
+}
+async function resolveKernelPython(spec) {
+    const argv0 = spec.argv?.[0];
+    if (!argv0)
+        return null;
+    if (path.isAbsolute(argv0))
+        return argv0;
+    const envPath = spec.env?.PATH || process.env.PATH;
+    return await findExecutableOnPath(argv0, envPath);
+}
+async function detectPythonExecutable() {
+    for (const cmd of DEFAULT_PYTHON_COMMANDS) {
+        try {
+            const { stdout } = await execFileAsync(cmd, ['-c', 'import sys; print(sys.executable)'], { env: process.env, timeout: 5000, maxBuffer: 1024 * 1024 });
+            const trimmed = stdout.trim();
+            if (trimmed)
+                return trimmed;
+        }
+        catch {
+            // Try next candidate
+        }
+    }
+    return null;
+}
+async function getDefaultKernelName() {
+    if (defaultKernelValue !== undefined) {
+        return defaultKernelValue;
+    }
+    if (!defaultKernelPromise) {
+        defaultKernelPromise = (async () => {
+            const pythonExe = await detectPythonExecutable();
+            if (!pythonExe)
+                return null;
+            const pythonReal = await resolveRealPath(pythonExe);
+            const specs = (0, kernelspec_1.discoverKernelSpecs)();
+            for (const spec of specs) {
+                const resolved = await resolveKernelPython(spec);
+                if (!resolved)
+                    continue;
+                const resolvedReal = await resolveRealPath(resolved);
+                if (resolvedReal === pythonReal) {
+                    return spec.name;
+                }
+            }
+            return null;
+        })()
+            .then((name) => {
+            defaultKernelValue = name;
+            return name;
+        })
+            .catch((err) => {
+            console.warn('[DefaultKernel] Failed to detect default kernel:', err);
+            defaultKernelValue = null;
+            return null;
+        });
+    }
+    return defaultKernelPromise;
+}
+function invalidateDefaultKernelName() {
+    defaultKernelValue = undefined;
+    defaultKernelPromise = null;
+}

package/node-server/dist/kernel/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Kernel Service Module
+ */
+export * from './types';
+export * from './kernelspec';
+export * from './session-store';
+export * from './kernel-service';

package/node-server/dist/kernel/index.js

@@ -0,0 +1,23 @@
+"use strict";
+/**
+ * Kernel Service Module
+ */
+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 __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./types"), exports);
+__exportStar(require("./kernelspec"), exports);
+__exportStar(require("./session-store"), exports);
+__exportStar(require("./kernel-service"), exports);

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

@@ -0,0 +1,290 @@
+/**
+ * Kernel Service
+ *
+ * Manages Jupyter kernel sessions - spawning, execution, and lifecycle.
+ * Uses ZeroMQ for kernel communication following the Jupyter messaging protocol.
+ */
+import { KernelOutput, ExecutionResult, ExecutionQueueInfo, StartKernelOptions, SessionInfo, KernelServiceConfig } from './types';
+import { SessionStore } from './session-store';
+import { KernelSpec } from './kernelspec';
+export declare class KernelService {
+    private sessions;
+    private fileToSession;
+    private kernelProcesses;
+    private processLifecycleHandlers;
+    private zmqSockets;
+    private sessionStore;
+    private config;
+    private kernelSpecsCache;
+    private ready;
+    private zmq;
+    private executionQueues;
+    private executionQueueSizes;
+    private shellRequestQueues;
+    private reattachInProgress;
+    private serverId;
+    private serverInstanceId;
+    private legacyCleanupWarned;
+    private cellOutputBuffers;
+    private cellOutputTracking;
+    private executingCellIds;
+    constructor(config?: KernelServiceConfig, sessionStore?: SessionStore);
+    setServerIdentity(serverId: string, serverInstanceId?: string): void;
+    /**
+     * Check if a PID is still alive.
+     */
+    private isPidAlive;
+    private attachProcessLifecycle;
+    private detachProcessLifecycle;
+    /**
+     * Load a Jupyter connection file.
+     */
+    private loadConnectionFile;
+    /**
+     * Initialize the service (lazy load ZeroMQ and discover kernels)
+     */
+    initialize(): Promise<void>;
+    /**
+     * Attempt to reattach to orphaned kernel sessions from a previous server run.
+     */
+    reattachOrphanedSessions(): Promise<{
+        attempted: number;
+        reattached: number;
+        failed: number;
+        skipped: number;
+    }>;
+    /**
+     * Check if service is ready
+     */
+    get isReady(): boolean;
+    /**
+     * Get available kernelspecs
+     */
+    getAvailableKernels(): KernelSpec[];
+    /**
+     * Re-run kernelspec discovery and refresh the in-memory cache.
+     *
+     * `getAvailableKernels()` caches once at startup and never expires, so a kernel
+     * registered while the server is running would otherwise stay invisible until a
+     * restart. Call this after registering/installing a kernel.
+     */
+    refreshKernelSpecs(): KernelSpec[];
+    /**
+     * Normalize file path for consistent lookup
+     */
+    private normalizePath;
+    /**
+     * Normalize notebook path for external callers (e.g., routes).
+     */
+    normalizeNotebookPath(filePath: string): string;
+    /**
+     * Save kernel preference for a notebook file.
+     */
+    saveNotebookKernelPreference(filePath: string, kernelName: string, serverId?: string | null): void;
+    /**
+     * Get kernel preference for a notebook file.
+     */
+    getNotebookKernelPreference(filePath: string): {
+        kernelName: string;
+        serverId: string | null;
+        updatedAt: number;
+    } | null;
+    /**
+     * Generate a connection file for the kernel
+     */
+    private allocateEphemeralPort;
+    private generateConnectionFile;
+    /**
+     * Start a new kernel session
+     */
+    startKernel(options?: StartKernelOptions): Promise<string>;
+    /**
+     * Wait for kernel to be ready by connecting to ZeroMQ channels.
+     *
+     * Returns the detected kernel execution state:
+     * - 'idle': kernel responded to kernel_info_request (ready for work)
+     * - 'busy': kernel PID is alive but shell channel is blocked (mid-execution)
+     *
+     * @param timeoutSeconds Optional override for startup timeout (default: use config)
+     * @param pid Optional kernel PID — used to distinguish "busy" from "dead" on timeout
+     */
+    private waitForReady;
+    /**
+     * Monitor a busy reattached kernel on iopub. When its current execution
+     * finishes (status: idle on iopub), verify shell connectivity and update
+     * the in-memory session status.
+     */
+    private monitorBusyKernel;
+    /**
+     * Send kernel_info_request and wait for reply to verify kernel is ready
+     * Throws if no reply received within timeout
+     */
+    private sendKernelInfoRequest;
+    /**
+     * Create a Jupyter protocol message
+     */
+    private createJupyterMessage;
+    /**
+     * Get or create kernel for a file (one notebook = one kernel).
+     * Returns whether a new session was created.
+     */
+    getOrCreateKernel(filePath: string, kernelName?: string): Promise<{
+        sessionId: string;
+        created: boolean;
+    }>;
+    /**
+     * Get existing kernel session ID for a notebook file (if any).
+     * Returns null if no live session is associated with the file.
+     */
+    getSessionIdForFile(filePath: string): string | null;
+    /**
+     * Check if a kernel session exists.
+     */
+    hasSession(sessionId: string): boolean;
+    /**
+     * Get the notebook file path associated with a session (if any).
+     * Used for output persistence when no UI is connected.
+     */
+    getSessionFilePath(sessionId: string): string | null;
+    /**
+     * Get the kernel name associated with a session (if any).
+     */
+    getSessionKernelName(sessionId: string): string | null;
+    /**
+     * Execute code in a kernel session
+     */
+    executeCode(sessionId: string, code: string, onOutput: (output: KernelOutput, cellId?: string | null) => Promise<void>, onQueueInfo?: (info: ExecutionQueueInfo) => void, cellId?: string | null): Promise<ExecutionResult>;
+    private enqueueExecution;
+    /**
+     * Queue shell socket requests to prevent concurrent receive operations
+     */
+    private enqueueShellRequest;
+    private reserveExecutionSlot;
+    private releaseExecutionSlot;
+    private formatExecutionError;
+    private executeCodeInternal;
+    /**
+     * Request code completion from the kernel
+     * Uses a separate queue for shell socket operations to avoid "socket busy" errors
+     */
+    complete(sessionId: string, code: string, cursorPos: number): Promise<{
+        status: string;
+        matches: string[];
+        cursor_start: number;
+        cursor_end: number;
+    }>;
+    /**
+     * Internal completion implementation (runs within shell queue)
+     */
+    private completeInternal;
+    /**
+     * Parse a Jupyter protocol message
+     */
+    private parseJupyterMessage;
+    /**
+     * Format display data for output
+     */
+    private formatDisplayData;
+    /**
+     * Strip ANSI escape codes from text
+     */
+    private stripAnsi;
+    private getOutputStats;
+    private ensureCellBuffers;
+    private ensureCellTracking;
+    /**
+     * Buffer an output for a cell. Returns the outputs actually stored (0 if truncated, 1 normally).
+     */
+    bufferOutput(sessionId: string, output: KernelOutput, cellId?: string | null): KernelOutput[];
+    /**
+     * Clear outputs for a specific cell (called on re-execute).
+     */
+    clearCellOutputs(sessionId: string, cellId: string): void;
+    /**
+     * Get all cell outputs for a session, grouped by cellId.
+     */
+    getAllCellOutputs(sessionId: string): Map<string, KernelOutput[]>;
+    getExecutingCellId(sessionId: string): string | null;
+    /**
+     * Stop a kernel session
+     */
+    stopKernel(sessionId: string): Promise<boolean>;
+    /**
+     * Check command line for a PID (best-effort).
+     */
+    private getPidCommand;
+    /**
+     * Get process start time (best-effort), used to prevent PID reuse mistakes.
+     */
+    private getProcessStartTime;
+    /**
+     * Best-effort check to ensure the PID is a kernel process we started.
+     */
+    private isExpectedKernelProcess;
+    /**
+     * Attempt to terminate a PID gracefully, then force kill.
+     */
+    private terminatePid;
+    private cleanupPersistedSessionArtifacts;
+    /**
+     * Cleanup kernel resources
+     */
+    private cleanupKernelResources;
+    /**
+     * Cleanup only in-memory tracking for a session (keeps connection file and session store).
+     */
+    private cleanupInMemorySession;
+    /**
+     * Interrupt kernel execution
+     */
+    interruptKernel(sessionId: string): Promise<boolean>;
+    /**
+     * Restart a kernel (in-place, preserving session ID like Python)
+     */
+    restartKernel(sessionId: string): Promise<boolean>;
+    /**
+     * Get session status
+     */
+    getSessionStatusFast(sessionId: string): SessionInfo | null;
+    getSessionStatus(sessionId: string): Promise<SessionInfo | null>;
+    /**
+     * Get all sessions
+     */
+    getAllSessions(): Promise<SessionInfo[]>;
+    /**
+     * Get dead sessions (orphaned or terminated) that can be cleaned up
+     */
+    getDeadSessions(): {
+        sessionId: string;
+        kernelName: string;
+        filePath: string | null;
+        status: string;
+        lastHeartbeat: number;
+    }[];
+    /**
+     * Cleanup dead sessions by deleting them from the database
+     */
+    cleanupDeadSessions(sessionIds?: string[]): Promise<number>;
+    /**
+     * Cleanup all sessions
+     */
+    cleanup(): Promise<void>;
+    /**
+     * Shutdown kernel service.
+     * If preserveKernels is true, keep kernel processes running and close the session store.
+     */
+    shutdown(options?: {
+        preserveKernels?: boolean;
+    }): Promise<void>;
+    /**
+     * Helper: sleep for ms milliseconds
+     */
+    private sleep;
+    /**
+     * Get memory usage (RSS) for multiple processes in MB
+     * Returns a map of pid -> memoryMb
+     * Cross-platform: uses /proc on Linux, ps on macOS
+     */
+    private getProcessMemoryMap;
+}
+export declare const kernelService: KernelService;