nebula-notebook 0.1.0

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

@@ -0,0 +1,29 @@
+/**
+ * Kernelspec Discovery
+ *
+ * Discovers Jupyter kernelspecs from standard locations.
+ * Similar to jupyter_client.kernelspec.find_kernel_specs()
+ */
+import { KernelSpec } from './types';
+export type { KernelSpec } from './types';
+/**
+ * Standard kernelspec search paths
+ */
+export declare function getKernelSearchPaths(): string[];
+/**
+ * Discover all available kernelspecs on the system
+ * Uses 60-second in-memory cache to avoid repeated disk I/O
+ */
+export declare function discoverKernelSpecs(forceRefresh?: boolean): KernelSpec[];
+/**
+ * Invalidate the kernelspec cache (call after installing a new kernel)
+ */
+export declare function invalidateKernelspecCache(): void;
+/**
+ * Get a specific kernelspec by name
+ */
+export declare function getKernelSpec(name: string): KernelSpec | null;
+/**
+ * Check if a kernelspec exists
+ */
+export declare function hasKernelSpec(name: string): boolean;

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

@@ -0,0 +1,210 @@
+"use strict";
+/**
+ * Kernelspec Discovery
+ *
+ * Discovers Jupyter kernelspecs from standard locations.
+ * Similar to jupyter_client.kernelspec.find_kernel_specs()
+ */
+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.getKernelSearchPaths = getKernelSearchPaths;
+exports.discoverKernelSpecs = discoverKernelSpecs;
+exports.invalidateKernelspecCache = invalidateKernelspecCache;
+exports.getKernelSpec = getKernelSpec;
+exports.hasKernelSpec = hasKernelSpec;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const os = __importStar(require("os"));
+// In-memory cache for kernelspecs (avoids repeated disk I/O)
+let kernelspecCache = null;
+let kernelspecCacheTime = 0;
+const KERNELSPEC_CACHE_TTL_MS = 60 * 1000; // 60 seconds
+/**
+ * Standard kernelspec search paths
+ */
+function getKernelSearchPaths() {
+    const paths = [];
+    const home = os.homedir();
+    // User-local paths
+    if (process.platform === 'darwin') {
+        paths.push(path.join(home, 'Library', 'Jupyter', 'kernels'));
+    }
+    else if (process.platform === 'win32') {
+        paths.push(path.join(home, 'AppData', 'Roaming', 'jupyter', 'kernels'));
+    }
+    else {
+        paths.push(path.join(home, '.local', 'share', 'jupyter', 'kernels'));
+    }
+    // System paths
+    if (process.platform !== 'win32') {
+        paths.push('/usr/local/share/jupyter/kernels');
+        paths.push('/usr/share/jupyter/kernels');
+    }
+    // Conda paths
+    const condaPrefix = process.env.CONDA_PREFIX;
+    if (condaPrefix) {
+        paths.push(path.join(condaPrefix, 'share', 'jupyter', 'kernels'));
+    }
+    // JUPYTER_PATH environment variable
+    const jupyterPath = process.env.JUPYTER_PATH;
+    if (jupyterPath) {
+        for (const p of jupyterPath.split(path.delimiter)) {
+            if (p) {
+                paths.push(path.join(p, 'kernels'));
+            }
+        }
+    }
+    // Homebrew Python paths (macOS)
+    if (process.platform === 'darwin') {
+        const brewPaths = [
+            '/opt/homebrew/share/jupyter/kernels',
+            '/usr/local/opt/python/Frameworks/Python.framework/Versions/Current/share/jupyter/kernels',
+        ];
+        paths.push(...brewPaths);
+    }
+    // pyenv paths
+    const pyenvRoot = process.env.PYENV_ROOT || path.join(home, '.pyenv');
+    if (fs.existsSync(pyenvRoot)) {
+        const versionsDir = path.join(pyenvRoot, 'versions');
+        if (fs.existsSync(versionsDir)) {
+            try {
+                const versions = fs.readdirSync(versionsDir);
+                for (const version of versions) {
+                    const kernelPath = path.join(versionsDir, version, 'share', 'jupyter', 'kernels');
+                    paths.push(kernelPath);
+                }
+            }
+            catch {
+                // Ignore read errors
+            }
+        }
+    }
+    return paths;
+}
+/**
+ * Read a kernel.json file and return the kernelspec
+ */
+function readKernelSpec(kernelDir) {
+    const kernelJsonPath = path.join(kernelDir, 'kernel.json');
+    if (!fs.existsSync(kernelJsonPath)) {
+        return null;
+    }
+    try {
+        const content = fs.readFileSync(kernelJsonPath, 'utf-8');
+        const spec = JSON.parse(content);
+        return {
+            name: path.basename(kernelDir),
+            displayName: spec.display_name || path.basename(kernelDir),
+            language: spec.language || 'python',
+            path: kernelDir,
+            argv: spec.argv,
+            env: spec.env,
+        };
+    }
+    catch (err) {
+        console.error(`Error reading kernelspec from ${kernelDir}:`, err);
+        return null;
+    }
+}
+/**
+ * Perform actual kernelspec discovery (disk I/O)
+ */
+function performKernelspecDiscovery() {
+    const specs = [];
+    const seenNames = new Set();
+    const searchPaths = getKernelSearchPaths();
+    for (const searchPath of searchPaths) {
+        if (!fs.existsSync(searchPath)) {
+            continue;
+        }
+        try {
+            const entries = fs.readdirSync(searchPath, { withFileTypes: true });
+            for (const entry of entries) {
+                if (!entry.isDirectory()) {
+                    continue;
+                }
+                const kernelName = entry.name;
+                if (seenNames.has(kernelName)) {
+                    continue;
+                }
+                const kernelDir = path.join(searchPath, kernelName);
+                const spec = readKernelSpec(kernelDir);
+                if (spec) {
+                    specs.push(spec);
+                    seenNames.add(kernelName);
+                }
+            }
+        }
+        catch (err) {
+            // Ignore errors reading directories
+        }
+    }
+    return specs;
+}
+/**
+ * Discover all available kernelspecs on the system
+ * Uses 60-second in-memory cache to avoid repeated disk I/O
+ */
+function discoverKernelSpecs(forceRefresh = false) {
+    const now = Date.now();
+    // Return from cache if valid
+    if (!forceRefresh && kernelspecCache && (now - kernelspecCacheTime) < KERNELSPEC_CACHE_TTL_MS) {
+        return kernelspecCache;
+    }
+    // Perform discovery and update cache
+    kernelspecCache = performKernelspecDiscovery();
+    kernelspecCacheTime = now;
+    return kernelspecCache;
+}
+/**
+ * Invalidate the kernelspec cache (call after installing a new kernel)
+ */
+function invalidateKernelspecCache() {
+    kernelspecCache = null;
+    kernelspecCacheTime = 0;
+}
+/**
+ * Get a specific kernelspec by name
+ */
+function getKernelSpec(name) {
+    const specs = discoverKernelSpecs();
+    return specs.find(s => s.name === name) || null;
+}
+/**
+ * Check if a kernelspec exists
+ */
+function hasKernelSpec(name) {
+    return getKernelSpec(name) !== null;
+}

package/node-server/dist/kernel/session-store.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Session Store
+ *
+ * SQLite-based persistence for kernel sessions.
+ * Enables recovery after server restarts.
+ */
+import { PersistedSession } from './types';
+export declare class SessionStore {
+    private db;
+    constructor(dbPath?: string);
+    /**
+     * Create tables if they don't exist
+     */
+    private initDb;
+    /**
+     * Insert or update a session
+     */
+    saveSession(session: PersistedSession): void;
+    /**
+     * Get a session by ID
+     */
+    getSession(sessionId: string): PersistedSession | null;
+    /**
+     * Get all active sessions
+     */
+    getActiveSessions(): PersistedSession[];
+    /**
+     * Get orphaned sessions (from previous server run)
+     */
+    getOrphanedSessions(serverId?: string): PersistedSession[];
+    /**
+     * Update heartbeat timestamp
+     */
+    updateHeartbeat(sessionId: string): void;
+    /**
+     * Update session status
+     */
+    updateStatus(sessionId: string, status: 'active' | 'orphaned' | 'terminated'): void;
+    /**
+     * Delete a session
+     */
+    deleteSession(sessionId: string): void;
+    /**
+     * Mark all active sessions as orphaned (called on startup)
+     */
+    markAllOrphaned(serverId?: string, serverInstanceId?: string): number;
+    /**
+     * Get session by file path
+     */
+    getSessionByFile(filePath: string): PersistedSession | null;
+    /**
+     * Cleanup old terminated/orphaned sessions
+     */
+    cleanupOldSessions(maxAgeHours?: number): number;
+    /**
+     * Get dead sessions (orphaned or terminated) - candidates for cleanup
+     */
+    getDeadSessions(serverId?: string): PersistedSession[];
+    /**
+     * Delete specific sessions by ID
+     */
+    deleteSessions(sessionIds: string[]): number;
+    /**
+     * 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;
+    /**
+     * Delete kernel preference for a notebook file.
+     */
+    deleteNotebookKernelPreference(filePath: string): void;
+    /**
+     * Close database connection
+     */
+    close(): void;
+    /**
+     * Convert database row to PersistedSession
+     */
+    private rowToSession;
+}

package/node-server/dist/kernel/session-store.js

@@ -0,0 +1,303 @@
+"use strict";
+/**
+ * Session Store
+ *
+ * SQLite-based persistence for kernel sessions.
+ * Enables recovery after server restarts.
+ */
+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;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SessionStore = void 0;
+const better_sqlite3_1 = __importDefault(require("better-sqlite3"));
+const path = __importStar(require("path"));
+class SessionStore {
+    db;
+    constructor(dbPath) {
+        const resolvedPath = dbPath || process.env.NEBULA_SESSIONS_DB_PATH || path.join(__dirname, '../../sessions.db');
+        this.db = new better_sqlite3_1.default(resolvedPath);
+        this.initDb();
+    }
+    /**
+     * Create tables if they don't exist
+     */
+    initDb() {
+        this.db.exec(`
+      CREATE TABLE IF NOT EXISTS sessions (
+        session_id TEXT PRIMARY KEY,
+        kernel_name TEXT NOT NULL,
+        file_path TEXT,
+        kernel_pid INTEGER,
+        server_id TEXT,
+        server_instance_id TEXT,
+        kernel_start_time TEXT,
+        status TEXT DEFAULT 'active',
+        created_at REAL NOT NULL,
+        last_heartbeat REAL NOT NULL,
+        connection_file TEXT,
+        connection_config TEXT
+      )
+    `);
+        this.db.exec(`
+      CREATE TABLE IF NOT EXISTS notebook_kernel_prefs (
+        file_path TEXT PRIMARY KEY,
+        kernel_name TEXT NOT NULL,
+        server_id TEXT,
+        updated_at REAL NOT NULL
+      )
+    `);
+        // Migration: add connection_config column if it doesn't exist
+        try {
+            this.db.exec('ALTER TABLE sessions ADD COLUMN connection_config TEXT');
+        }
+        catch {
+            // Column already exists
+        }
+        try {
+            this.db.exec('ALTER TABLE sessions ADD COLUMN server_id TEXT');
+        }
+        catch {
+            // Column already exists
+        }
+        try {
+            this.db.exec('ALTER TABLE sessions ADD COLUMN server_instance_id TEXT');
+        }
+        catch {
+            // Column already exists
+        }
+        try {
+            this.db.exec('ALTER TABLE sessions ADD COLUMN kernel_start_time TEXT');
+        }
+        catch {
+            // Column already exists
+        }
+        this.db.exec(`
+      CREATE INDEX IF NOT EXISTS idx_sessions_status
+      ON sessions(status)
+    `);
+        this.db.exec(`
+      CREATE INDEX IF NOT EXISTS idx_sessions_file_path
+      ON sessions(file_path) WHERE file_path IS NOT NULL
+    `);
+        this.db.exec(`
+      CREATE INDEX IF NOT EXISTS idx_notebook_kernel_prefs_updated_at
+      ON notebook_kernel_prefs(updated_at)
+    `);
+    }
+    /**
+     * Insert or update a session
+     */
+    saveSession(session) {
+        const stmt = this.db.prepare(`
+      INSERT OR REPLACE INTO sessions
+      (session_id, kernel_name, file_path, kernel_pid,
+       server_id, server_instance_id, kernel_start_time,
+       status, created_at, last_heartbeat,
+       connection_file, connection_config)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `);
+        stmt.run(session.sessionId, session.kernelName, session.filePath, session.kernelPid, session.serverId ?? null, session.serverInstanceId ?? null, session.kernelStartTime ?? null, session.status, session.createdAt, session.lastHeartbeat, session.connectionFile, session.connectionConfig);
+    }
+    /**
+     * Get a session by ID
+     */
+    getSession(sessionId) {
+        const stmt = this.db.prepare('SELECT * FROM sessions WHERE session_id = ?');
+        const row = stmt.get(sessionId);
+        if (row) {
+            return this.rowToSession(row);
+        }
+        return null;
+    }
+    /**
+     * Get all active sessions
+     */
+    getActiveSessions() {
+        const stmt = this.db.prepare("SELECT * FROM sessions WHERE status = 'active'");
+        const rows = stmt.all();
+        return rows.map(row => this.rowToSession(row));
+    }
+    /**
+     * Get orphaned sessions (from previous server run)
+     */
+    getOrphanedSessions(serverId) {
+        if (serverId) {
+            const stmt = this.db.prepare("SELECT * FROM sessions WHERE status = 'orphaned' AND (server_id = ? OR server_id IS NULL)");
+            const rows = stmt.all(serverId);
+            return rows.map(row => this.rowToSession(row));
+        }
+        const stmt = this.db.prepare("SELECT * FROM sessions WHERE status = 'orphaned'");
+        const rows = stmt.all();
+        return rows.map(row => this.rowToSession(row));
+    }
+    /**
+     * Update heartbeat timestamp
+     */
+    updateHeartbeat(sessionId) {
+        const stmt = this.db.prepare('UPDATE sessions SET last_heartbeat = ? WHERE session_id = ?');
+        stmt.run(Date.now() / 1000, sessionId);
+    }
+    /**
+     * Update session status
+     */
+    updateStatus(sessionId, status) {
+        const stmt = this.db.prepare('UPDATE sessions SET status = ? WHERE session_id = ?');
+        stmt.run(status, sessionId);
+    }
+    /**
+     * Delete a session
+     */
+    deleteSession(sessionId) {
+        const stmt = this.db.prepare('DELETE FROM sessions WHERE session_id = ?');
+        stmt.run(sessionId);
+    }
+    /**
+     * Mark all active sessions as orphaned (called on startup)
+     */
+    markAllOrphaned(serverId, serverInstanceId) {
+        if (serverId && serverInstanceId) {
+            const stmt = this.db.prepare("UPDATE sessions SET status = 'orphaned' WHERE status = 'active' AND (server_id = ? OR server_id IS NULL) AND (server_instance_id IS NULL OR server_instance_id != ?)");
+            const result = stmt.run(serverId, serverInstanceId);
+            return result.changes;
+        }
+        const stmt = this.db.prepare("UPDATE sessions SET status = 'orphaned' WHERE status = 'active'");
+        const result = stmt.run();
+        return result.changes;
+    }
+    /**
+     * Get session by file path
+     */
+    getSessionByFile(filePath) {
+        const stmt = this.db.prepare("SELECT * FROM sessions WHERE file_path = ? AND status = 'active'");
+        const row = stmt.get(filePath);
+        if (row) {
+            return this.rowToSession(row);
+        }
+        return null;
+    }
+    /**
+     * Cleanup old terminated/orphaned sessions
+     */
+    cleanupOldSessions(maxAgeHours = 24) {
+        const cutoff = (Date.now() / 1000) - (maxAgeHours * 3600);
+        const stmt = this.db.prepare("DELETE FROM sessions WHERE status IN ('terminated', 'orphaned') AND last_heartbeat < ?");
+        const result = stmt.run(cutoff);
+        return result.changes;
+    }
+    /**
+     * Get dead sessions (orphaned or terminated) - candidates for cleanup
+     */
+    getDeadSessions(serverId) {
+        if (serverId) {
+            const stmt = this.db.prepare("SELECT * FROM sessions WHERE status IN ('orphaned', 'terminated') AND (server_id = ? OR server_id IS NULL)");
+            const rows = stmt.all(serverId);
+            return rows.map(row => this.rowToSession(row));
+        }
+        const stmt = this.db.prepare("SELECT * FROM sessions WHERE status IN ('orphaned', 'terminated')");
+        const rows = stmt.all();
+        return rows.map(row => this.rowToSession(row));
+    }
+    /**
+     * Delete specific sessions by ID
+     */
+    deleteSessions(sessionIds) {
+        if (sessionIds.length === 0)
+            return 0;
+        const placeholders = sessionIds.map(() => '?').join(',');
+        const stmt = this.db.prepare(`DELETE FROM sessions WHERE session_id IN (${placeholders})`);
+        const result = stmt.run(...sessionIds);
+        return result.changes;
+    }
+    /**
+     * Save kernel preference for a notebook file.
+     */
+    saveNotebookKernelPreference(filePath, kernelName, serverId) {
+        const stmt = this.db.prepare(`
+      INSERT OR REPLACE INTO notebook_kernel_prefs
+      (file_path, kernel_name, server_id, updated_at)
+      VALUES (?, ?, ?, ?)
+    `);
+        stmt.run(filePath, kernelName, serverId ?? null, Date.now() / 1000);
+    }
+    /**
+     * Get kernel preference for a notebook file.
+     */
+    getNotebookKernelPreference(filePath) {
+        const stmt = this.db.prepare('SELECT kernel_name, server_id, updated_at FROM notebook_kernel_prefs WHERE file_path = ?');
+        const row = stmt.get(filePath);
+        if (!row)
+            return null;
+        return {
+            kernelName: row.kernel_name,
+            serverId: row.server_id ?? null,
+            updatedAt: row.updated_at,
+        };
+    }
+    /**
+     * Delete kernel preference for a notebook file.
+     */
+    deleteNotebookKernelPreference(filePath) {
+        const stmt = this.db.prepare('DELETE FROM notebook_kernel_prefs WHERE file_path = ?');
+        stmt.run(filePath);
+    }
+    /**
+     * Close database connection
+     */
+    close() {
+        this.db.close();
+    }
+    /**
+     * Convert database row to PersistedSession
+     */
+    rowToSession(row) {
+        return {
+            sessionId: row.session_id,
+            kernelName: row.kernel_name,
+            filePath: row.file_path,
+            kernelPid: row.kernel_pid,
+            serverId: row.server_id,
+            serverInstanceId: row.server_instance_id,
+            kernelStartTime: row.kernel_start_time,
+            status: row.status,
+            createdAt: row.created_at,
+            lastHeartbeat: row.last_heartbeat,
+            connectionFile: row.connection_file,
+            connectionConfig: row.connection_config,
+        };
+    }
+}
+exports.SessionStore = SessionStore;