dsh-better-sidebar-jupyter

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