dsh-better-sidebar-jupyter

Jupyter notebook support for dsh-better-sidebar: .ipynb files open inline in the sidebar editor as a runnable notebook view — Python syntax highlighting, cell execution through a lazy-start Python kernel (jupyter_client + ipykernel via python/bridge.py), streaming outputs, and save-back.

Merged from the Jupyter support of @dong-victor/dsh-explorer, adapted to the better-sidebar plugin architecture: the viewer registers through the ctx.betterSidebar.registerFileViewer service, and every route is session-scoped — the notebook must live inside the conversation's working directory.

Requirements

• dsh-better-sidebar ≥ 0.13.0 (the registerFileViewer service)
• Python with jupyter_client and ipykernel for cell execution:

pip install jupyter_client ipykernel

Install

cd ~/.dsh && dsh plugin --profile web add @dong-victor/dsh-better-sidebar-jupyter

(or add it from the Side card settings → 文件预览 → “添加预览插件”.)

What you get

• .ipynb opens in the sidebar editor (single-click in the explorer / any

open-path flow), rendered by the inline notebook viewer.

• IDEA/PyCharm-style run mode — shortcuts and toolbar mirror IntelliJ's

Jupyter support (Windows keymap): - Ctrl+Enter — run the current cell (stays in the cell for editing). - Shift+Enter — run the current cell and select the cell below; when there is no cell below, a new one is created (IDEA behavior). - Ctrl+Alt+Shift+Enter — run all code cells. - Ctrl+F2 — interrupt the running kernel. - Ctrl+Home / Ctrl+End — move the caret to the start/end of the current cell; outside an editor, focus the first/last cell of the notebook. - Ctrl/Cmd+S — save.

• IDEA toolbar: ▶ Run cell and select below · ▶▶ Run all · ■ Interrupt ·

↻ Restart · ⏻ Shutdown · 🧹 Clear all outputs · ＋ Add cell below · ↑/↓ Move cell · cell-type selector (Code/Markdown/Raw) · ⇡/⇣ select above/below · kernel status widget (state + kernel name) · save.

• Per-cell IDEA affordances: green ▶ gutter run button on every code cell

(hover/selected), In [n] execution counter, Out[n] on results, and the execution duration in the cell's lower-left corner (hover shows the completion date/time). Error outputs render as collapsible tracebacks (IDEA-style summary row + expand toggle).

• Lazy kernel: the Python bridge starts on the first run — no startup cost for

plain browsing. Kernels keep running in the background while the editor is closed, and finished executions are written back into the .ipynb file (run-all survives tab switches / session switches / reconnects). Reopening a notebook — or coming back after switching sessions — re-syncs the whole batch: the executing cell shows as running with its latest partial output, and the queued tail of a run-all batch shows as queued.

• Explorer indicator: notebooks whose kernel is alive get a green dot

next to their file name in the sidebar file browser (pulsing while a cell executes), so a background run is visible even with the notebook closed.

• Syntax highlighting follows the app theme (IDEA/Darcula-style Python

highlighting, --dsw-* tokens).

Architecture

• src/index.ts (host half): mounts the fenced routes

/api/dsh-better-sidebar-jupyter/* (env / notebook GET+PUT / kernel lifecycle) and the kernel WebSocket upgrade, with one KernelManager per notebook path. Every request carries sessionId (+ optional cwd) and a path; src/host/gate.ts requires the canonical path to live inside the session's authoritative working directory.

• python/bridge.py: a JSON-lines RPC shim that owns the real Jupyter kernel

(all ZeroMQ handling stays in Python — no native ZMQ bindings in Node).

• src/client/ (client half): the .ipynb file viewer (NotebookView) wraps

the notebook editor UI (EditorView + cells + outputs), talking to the host through a session-scoped JupyterApi.

Security

All routes pass the same browser-trust fence as the DSH /api gateway (Host-header loopback or trustedHosts), and notebook paths are gated to the session's cwd — a cross-site page cannot reach the kernel or read/write files outside the conversation's directory.

License

MIT