nebula-notebook 0.1.0 → 0.2.0

package/README.md

@@ -1,9 +1,98 @@
 # Nebula Notebook
 
-Nebula is an AI-native notebook computing environment built for what's coming next. It also comes with an optimized user experience even if you use no AI features at all.
+Nebula is an agent-native notebook — built for you and your AI to work in the same cells, and a fast, polished one even if you never touch the AI.
+
+<p align="center">
+  <!-- 2½-min product tour. Uploaded into the `demo-assets` release description, so GitHub
+       transcodes it and streams it inline via the user-attachments URL below (video/mp4,
+       range requests, no attachment disposition). The 12 MB original also stays attached to
+       that release as a downloadable asset. Neither is committed to the repo, so clones stay
+       lean. Renderers that strip <video> (npm, some mirrors) fall back to the link inside. -->
+  <video src="https://github.com/user-attachments/assets/4a9ec9ce-9ac0-4540-b35a-27c1b97a20b1" controls muted width="940" poster="https://raw.githubusercontent.com/jzthree/nebula-notebook/main/docs/assets/nebula-hero.svg">
+    <a href="https://github.com/jzthree/nebula-notebook/releases/download/demo-assets/nebula-demo-16x9-v10-hq.mp4">Watch the 2½-minute product tour</a>
+  </video>
+</p>
+<p align="center"><sub>▶ <a href="https://github.com/user-attachments/assets/4a9ec9ce-9ac0-4540-b35a-27c1b97a20b1">Watch the 2½-minute tour</a> · or skim the autoplay clips below</sub></p>
+
+## Highlights
+
+- **Agent-native** — Claude Code, Codex, Cursor & friends operate notebooks through MCP (`npx nebula-notebook-mcp setup-mcp`); an agent terminal is built into every notebook, with one-click launch pre-briefed on your server and notebook
+- **Edit while the agent edits** — per-cell optimistic concurrency: if an agent's write conflicts with yours, it's rejected and handed your current content to retry against — nothing is silently overwritten
+- **"Fix with agent"** on any failing cell, plus per-cell prompts — both inject straight into the agent's terminal, context included
+- **Jupyter kernels** over ZeroMQ (Python, Julia, R, …) that survive dev-server restarts and reattach
+- **Rich outputs** — Plotly MIME rendering and Nebula-native interactive JS outputs, in a virtualized cell list that stays fast on large notebooks
+- **Runs anywhere** — `npx nebula-notebook`, TOTP 2FA, and multi-server clusters behind a single UI
+- **…and it runs where your compute lives** — on an HPC login node, allocate a scheduler job right from the kernel menu (partition/QoS/GPU, with a live queue-load monitor and soonest-queue hint) and your kernel runs on the compute node — no sbatch script, no SSH tunnel. Detection-gated: invisible off-cluster
+
+## See it in action
+
+**A failing cell, fixed by the agent live** — the cell errors, the agent rewrites it (presence ring on the cell it's touching) and reruns it clean:
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/jzthree/nebula-notebook/main/docs/assets/demo/scene-agent.gif" alt="A code cell throws a KeyError; an agent session starts, rewrites the cell live with a purple presence ring, reruns it, and the clean output appears" width="760">
+</p>
+
+**Interactive outputs, no widget plumbing** — `application/vnd.nebula.web+json` widgets respond to clicks:
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/jzthree/nebula-notebook/main/docs/assets/demo/scene-widget.gif" alt="A Nebula-native interactive web output: clicking Resample re-rolls the bar chart live" width="760">
+</p>
+
+**Time-travel through your edit history** — preview any past moment with diff highlighting, then restore:
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/jzthree/nebula-notebook/main/docs/assets/demo/scene-history.gif" alt="The History panel: clicking a past edit previews the notebook at that moment with an orange modified-cell highlight and a Restore option" width="760">
+</p>
+
+**Find across the whole notebook** — regex search with live match counts:
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/jzthree/nebula-notebook/main/docs/assets/demo/scene-search.gif" alt="Notebook-wide search: typing a query highlights every match across cells with a running match count" width="760">
+</p>
+
+<sub>All clips captured headlessly from the running app — regenerate with <code>python scripts/demo-shoot.py all</code>.</sub>
 
 ## Quick Start
 
+### On your machine
+
+```bash
+npx nebula-notebook
+```
+
+On first start a QR code appears in the terminal — scan it with an authenticator app (Google Authenticator, Authy, …), then open http://localhost:3000 and enter the 6-digit code. A startup banner shows the URLs and what was detected.
+
+Nebula itself is pure Node — but running notebooks needs a Python (3.10+) with `ipykernel` on the server machine. If none is found, the kernel menu detects your Python environments (venv, conda, uv, pixi, system) and shows the exact setup command for each; environments that already have `ipykernel` register with one click.
+
+### On a cluster / remote server
+
+Run the server where your files and compute live; browse it through one SSH tunnel:
+
+```bash
+# on the cluster login node (inside tmux so it outlives your session)
+tmux new -s nebula
+npx nebula-notebook
+
+# from your laptop
+ssh -L 3000:localhost:3000 <login-node>     # then open http://localhost:3000
+```
+
+If a SLURM scheduler is present, the kernel menu gains **New compute allocation** — your kernels run on compute nodes, no sbatch script, no extra tunnels. Full guide (bastions, persistent runs, agent placements, troubleshooting): [docs/CLUSTER_SETUP.md](docs/CLUSTER_SETUP.md).
+
+### Let agents in
+
+To let agents (Claude Code, Codex, Cursor, Gemini CLI, …) operate your notebooks, register the Nebula MCP on the machine where your agent runs:
+
+```bash
+npx nebula-notebook-mcp setup-mcp
+```
+
+Then open a notebook, click **Agent**, and launch Claude Code or Codex right in the notebook's terminal — or use the `nebula` CLI (`npx -p nebula-notebook-mcp nebula --help`) for a lighter, shell-first integration.
+
+### From source (latest)
+
+npm releases are point-in-time snapshots — to get the latest changes, install from source:
+
 ```bash
 git clone https://github.com/jzthree/nebula-notebook.git
 cd nebula-notebook
@@ -12,10 +101,6 @@ npm install
 npm run start
 ```
 
-On first start, a QR code will appear in the terminal. Scan it with an authenticator app (Google Authenticator, Authy, etc.) to set up 2FA.
-
-Open http://localhost:3000 and enter your 6-digit code.
-
 ## Root Directory
 
 Set the server root directory (default is your home directory):
@@ -29,8 +114,8 @@ This root is used for the file browser and terminals. You can also change it fro
 ## Features
 
 **Core**
-- Real Jupyter kernel execution (Python, Julia, R, etc.)
-- Real filesystem access - open notebooks from anywhere
+- Jupyter kernel execution (Python, Julia, R, etc.)
+- Built-in file browser — open notebooks anywhere on disk
 - Autosave with crash recovery
 - Undo/redo with full edit history
 
@@ -39,10 +124,11 @@ This root is used for the file browser and terminals. You can also change it fro
 - Search & replace across all cells (Cmd/Ctrl+F)
 - Keyboard shortcuts (Shift+Enter to run, Cmd+S to save, etc.)
 
-**AI Assistant**
-- Multi-provider support: Gemini, OpenAI, Anthropic
-- Code generation and error fixing
-- Context-aware suggestions
+**Agents**
+- Agent terminal built into every notebook — one click launches Claude Code or Codex, pre-briefed with the server URL and notebook path
+- "Fix with agent" on any failing cell, and per-cell prompts, injected straight into the agent's terminal
+- Full MCP toolset ([`nebula-notebook-mcp`](https://www.npmjs.com/package/nebula-notebook-mcp)): read/edit/execute cells, manage kernels and files — from any agent on any machine
+- Agent sessions lock the notebook during edits and sync live into the UI
 
 **Editor**
 - Syntax highlighting with CodeMirror
@@ -68,8 +154,12 @@ See [docs/RICH_OUTPUTS.md](docs/RICH_OUTPUTS.md) for examples, payload format, s
 
 ## Prerequisites
 
-- Node.js 18+
-- Python 3.10+ with Jupyter kernels (`pip install ipykernel`)
+- Node.js 20+
+- Python 3.10+ with `ipykernel`, on the machine running the server (other Jupyter kernels — Julia, R, … — work too)
+
+No ipykernel yet? Open the kernel menu in the UI: it detects your Python environments (venv, conda, uv, pixi, Homebrew, system), registers ready ones with one click, and shows the exact install command for the rest — including the PEP 668 "externally managed" cases (uv/Homebrew/system Python) where `pip install` is blocked and an isolated env is the right move.
+
+Using **R** (or another non-Python kernel)? See [docs/R_KERNEL.md](docs/R_KERNEL.md) — registering IRkernel and the one-line fix for the common headless-server plotting error.
 
 ## Project Structure
 
@@ -93,19 +183,21 @@ nebula-notebook/
 
 ## MCP Adapter
 
-The MCP adapter now lives in this repository under `packages/mcp`. It remains a
-separate Node package so it can be installed on a local agent/client machine even
-when the Nebula Notebook server is running elsewhere.
+The MCP adapter is published as [`nebula-notebook-mcp`](https://www.npmjs.com/package/nebula-notebook-mcp)
+and lives in this repository under `packages/mcp`. It is a separate package so it
+can be installed on a local agent/client machine even when the Nebula Notebook
+server is running elsewhere.
 
 ```bash
-# From this repo: build or run the MCP server
+# Register the MCP with your installed agent CLIs (Claude Code, Codex, …)
+npx nebula-notebook-mcp setup-mcp
+
+# Agents must call connect_server(base_url) once per session —
+# the base_url is the URL you open Nebula at, e.g. http://localhost:3000
+
+# From a repo checkout instead: build or run the MCP server
 npm run mcp:build
 npm run mcp
-
-# Client-only install from source
-cd packages/mcp
-npm install
-npm run build
 ```
 
 ## Authentication
@@ -201,6 +293,14 @@ Servers without the correct secret will be rejected during registration.
 - Client servers need access to the same filesystem paths as the main server (for notebook files)
 - Each server runs its own Jupyter kernels locally
 
+### Scheduler-backed compute (HPC)
+
+On an HPC login node you don't launch client servers by hand — the scheduler does it for you. When Nebula detects a scheduler (SLURM first — `sbatch`/`squeue` on `PATH`), the kernel menu's **Server** section grows a **+ New compute allocation** entry:
+
+- **Allocate from the notebook.** Pick a partition + QoS (only the ones your account may actually submit to), CPUs, memory, GPUs, and walltime. A **live cluster-load panel** sits beside the form — idle CPUs, idle GPUs *by type*, and per-queue backlog with your own jobs highlighted — and recommends the queue you'll land on soonest. Choosing a GPU queue narrows the GPU-type list to the models that queue actually has, so you can't request one it doesn't offer.
+- **It just becomes a server.** Nebula submits the job; the allocation shows up in the Server list as *"Queued · waiting…"*, then flips to a normal online server the moment the job starts. Select it and your kernels run on the compute node — proxied over the same WebSocket path as any remote kernel, so ZeroMQ never crosses the network. One allocation hosts **many** kernels: queue once, run several notebooks in it. When the walltime ends (or you cancel), the server drops out of the list and its kernels are marked done.
+- **Nothing changes off-cluster.** The whole feature is detection-gated — no scheduler on the machine, no compute UI. Design and internals in [docs/SLURM_COMPUTE.md](docs/SLURM_COMPUTE.md).
+
 ## Tips
 
 **Persistent Terminals**: Access standalone terminals via URL:
@@ -213,9 +313,9 @@ Terminals persist as long as the server runs. Bookmark different terminals for q
 ## Tech Stack
 
 - **Frontend**: React 19, TypeScript, Vite, Tailwind CSS, CodeMirror
-- **Backend**: Node.js, Express, ZeroMQ (Jupyter kernel protocol)
+- **Backend**: Node.js, Fastify, ZeroMQ (Jupyter kernel protocol)
 - **Auth**: TOTP (otplib), JWT (jsonwebtoken)
-- **AI**: OpenAI, Anthropic, Google GenAI SDKs
+- **Agents**: MCP (`nebula-notebook-mcp`), used by Claude Code, Codex, and other agent CLIs
 
 ## License
 

package/dist/assets/errorwidget-C4r2j2DQ.js

@@ -0,0 +1,5 @@
+import{a as d,L as c,D as l,E as a}from"./services-shim-D6p_A67v.js";function h(t,s){class n extends l{constructor(r,i){r=Object.assign(Object.assign({},r),{_view_name:"ErrorWidgetView",_view_module:"@jupyter-widgets/base",_model_module_version:a,_view_module_version:a,msg:s,error:t}),super(r,i),this.comm_live=!0}}return n}class g extends d{generateErrorMessage(){return{msg:this.model.get("msg"),stack:String(this.model.get("error").stack)}}render(){const{msg:s,stack:n}=this.generateErrorMessage();this.el.classList.add("jupyter-widgets");const e=document.createElement("div");e.classList.add("jupyter-widgets-error-widget","icon-error"),e.innerHTML=c;const r=document.createElement("pre");r.style.textAlign="center",r.innerText="Click to show javascript error.",e.append(r),this.el.appendChild(e);let i,o;this.el.onclick=()=>{e.classList.contains("icon-error")&&(o=o||e.clientHeight,i=i||e.clientWidth,e.classList.remove("icon-error"),e.innerHTML=`
+        <pre>[Open Browser Console for more detailed log - Double click to close this message]
+${s}
+${n}</pre>
+        `,e.style.height=`${o}px`,e.style.width=`${i}px`,e.classList.add("text-error"))},this.el.ondblclick=()=>{e.classList.contains("text-error")&&(e.classList.remove("text-error"),e.innerHTML=c,e.append(r),e.classList.add("icon-error"))}}}function E(t,s){return class extends g{generateErrorMessage(){return{msg:s,stack:String(t instanceof Error?t.stack:t)}}}}export{g as E,E as a,h as c};