nebula-notebook 0.1.1 → 0.2.1

package/README.md

@@ -1,39 +1,120 @@
 # Nebula Notebook
 
-Nebula is an agent-native notebook computing environment built for what's coming next: real Jupyter kernels, real filesystem access, and a notebook that agents (Claude Code, Codex, …) can drive end-to-end through MCP — while staying a fast, polished notebook even if you never touch the AI features.
+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.
 
-![Nebula Notebook — agents drive the notebook via MCP](https://raw.githubusercontent.com/jzthree/nebula-notebook/main/docs/assets/nebula-hero.svg)
+<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/jzhoulab/nebula-notebook/main/docs/assets/nebula-hero.svg">
+    <a href="https://github.com/jzhoulab/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
+
+- **Your notebook and your agent, at the same time** — Claude Code, Codex, Cursor & friends drive notebooks through the **MCP** server or the **`nebula` CLI** (also installable as a Claude Code skill), and every notebook has a built-in agent terminal, one-click launched and pre-briefed. You keep editing *while* the agent edits: per-cell optimistic concurrency hands a conflicting agent your current content to retry against — nothing is silently overwritten. **"Fix with agent"** sits on every failing cell, and any cell takes a plain-English prompt
+- **Never lose work** — **infinite undo/redo**, journaled to disk and surviving reloads — every edit, yours and the agent's; the History panel time-travels to any past moment with diff highlighting and one-click restore; autosave that notices when the file changed underneath you
+- **Everything smoother** — big notebooks open instantly (virtualized cells), Run All shows live queue positions and per-cell timings, `tqdm` renders as one clean bar, and there's real whole-notebook search & replace (regex included) plus a keyboard-first cell navigator
+- **Rich outputs, no widget plumbing** — Plotly MIME rendering and Nebula-native interactive JS outputs that respond to clicks
+- **Notebooks your git history will thank you for** — first-class **`.qmd` and `.py` (percent)** notebooks: clean text diffs, outputs never serialized
+- **Meets your environment where it is** — detects conda / venv / uv / pixi / system Pythons with one-click kernel registration (and exact guidance when `ipykernel` is missing); Jupyter kernels over ZeroMQ (Python, Julia, R, …) survive server restarts and reattach
+- **Runs anywhere — including where your compute lives** — `npx nebula-notebook`, TOTP 2FA, multi-server clusters behind one UI; on an HPC login node, allocate a scheduler job right from the kernel menu (partition/QoS/GPU, live queue-load monitor) and your kernel runs on the compute node — no sbatch script, no SSH tunnel, 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/jzhoulab/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/jzhoulab/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/jzhoulab/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/jzhoulab/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
 ```
 
-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.
+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).
 
-Open http://localhost:3000 and enter your 6-digit code.
+### Let agents in
 
-To let agents (Claude Code, Codex, Cursor, Gemini CLI, …) drive your notebooks, register the Nebula MCP on the machine where your agent runs:
+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.
+Then open a notebook, click **Agent**, and launch Claude Code or Codex right in the notebook's terminal. Prefer a command line? The same package ships the shell-first `nebula` CLI (`npx -p nebula-notebook-mcp nebula --help`); run `nebula setup-skill` to install it as a **Claude Code skill** so agents outside a Nebula terminal know how to drive it.
+
+**Prerequisite when the agent runs on your own machine** (Agent tab → *on: my machine*, or any terminal outside Nebula): that machine needs the `nebula` CLI available. Node.js ≥ 20 is enough — the agent is briefed to fall back to `npx -p nebula-notebook-mcp nebula …` when `nebula` isn't on PATH; installing `npm i -g nebula-notebook-mcp` skips the npx download. Agents launched in a Nebula terminal on the server need nothing extra — the CLI is pre-wired there.
 
 ### 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
+git clone https://github.com/jzhoulab/nebula-notebook.git
 cd nebula-notebook
-npm install
+npm install                # dependencies only (root + subpackages) — no build yet
+```
 
-npm run start
+> Building from source needs devDependencies. If your shell sets `NODE_ENV=production`
+> (common on servers), use `npm install --include=dev` — otherwise the build tools
+> (`tsc`, `vite`) are skipped and the build steps below fail with "command not found".
+
+To run the same production server `npx nebula-notebook` gives you (UI + API on :3000), build both halves once, then start it:
+
+```bash
+npm run build              # frontend → dist/
+npm run node-server:build  # backend  → node-server/dist/
+node bin/nebula-notebook.js          # accepts the same flags, e.g. --workdir
 ```
 
+For hacking on Nebula itself there's also a dev mode with hot reload (`npm run start` — Vite on :3000, API on :8000); rebuild with the two build commands above after `git pull` to refresh a production install.
+
 ## Root Directory
 
 Set the server root directory (default is your home directory):
@@ -47,10 +128,10 @@ 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
+- Infinite undo/redo, journaled to disk (survives reloads) — time-travel to any past state with diff preview and one-click restore
 
 **Navigation**
 - Table of Contents breadcrumb - auto-generated from markdown headers
@@ -60,7 +141,8 @@ This root is used for the file browser and terminals. You can also change it fro
 **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
+- Two ways for agents to plug in, same operations under the hood — **MCP** ([`nebula-notebook-mcp`](https://www.npmjs.com/package/nebula-notebook-mcp)) for tool-calling agents, and the shell-first **`nebula` CLI** (`nb read/edit/run`, `kernel`, `session`, `compute`) for scripting; the CLI also installs as a **Claude Code skill** (`nebula setup-skill`) for agents running outside a Nebula terminal
+- Full toolset on both: read/edit/execute cells, manage kernels and files, and allocate cluster compute — from any agent on any machine
 - Agent sessions lock the notebook during edits and sync live into the UI
 
 **Editor**
@@ -87,8 +169,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
 
@@ -222,6 +308,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:
@@ -236,7 +330,7 @@ Terminals persist as long as the server runs. Bookmark different terminals for q
 - **Frontend**: React 19, TypeScript, Vite, Tailwind CSS, CodeMirror
 - **Backend**: Node.js, Fastify, ZeroMQ (Jupyter kernel protocol)
 - **Auth**: TOTP (otplib), JWT (jsonwebtoken)
-- **Agents**: MCP (`nebula-notebook-mcp`) driven by Claude Code, Codex, and other agent CLIs
+- **Agents**: MCP and the `nebula` CLI (also installable as a Claude Code skill), both in [`nebula-notebook-mcp`](https://www.npmjs.com/package/nebula-notebook-mcp), used by Claude Code, Codex, and other agent CLIs
 
 ## License
 

package/dist/assets/errorwidget-Wy5ajPiM.js

@@ -0,0 +1,5 @@
+import{a as d,L as c,D as l,E as a}from"./services-shim-BirHVsih.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};