Improved Notebook

.github/workflows/ci.yml

@@ -0,0 +1,28 @@
+name: CI
+
+on:
+  pull_request:
+    branches: [main]
+  push:
+    branches: [main]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    env:
+      CGO_ENABLED: 0
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-go@v5
+        with:
+          go-version: "1.24.x"
+          cache: true
+
+      - run: go mod download
+      - run: go vet ./...
+      - run: go build -o rizin-notebook -ldflags "-X main.NBVERSION=$(git rev-parse --short HEAD)"

.gitignore

@@ -1,3 +1,47 @@
-rz-notebook
 rizin-notebook
-.test-data
+rizin-notebook.exe
+rizin-notebook.exe~
+build-local/
+build-local-*/
+*.test
+*.out
+coverage.out
+.test-data
+.rizin-notebook/
+**/build/
+**/build-*/
+**/cmake-build-*/
+**/CMakeFiles/
+**/CMakeCache.txt
+**/cmake_install.cmake
+**/compile_commands.json
+**/Makefile
+**/*.sln
+**/*.vcxproj
+**/*.vcxproj.filters
+**/*.vcxproj.user
+**/*.dir/
+**/*.tlog
+*.obj
+*.o
+*.a
+*.lib
+*.dll
+*.dylib
+*.so
+*.exp
+*.pdb
+.env
+.env.*
+.vscode/
+.vs/
+cutter-notebook-plugin/build/
+cutter-notebook-plugin/cmake-build-*/
+cutter-notebook-plugin/.qt/
+cutter-notebook-plugin/*.zip
+rizin-notebook-plugin/build/
+rizin-notebook-plugin/cmake-build-*/
+.DS_Store
+Thumbs.db
+embedded-rizin-check.txt
+embedded-rizin-plugins.txt

README.md

@@ -1,19 +1,150 @@
-# Rizin Notebook
+# Rizin Notebook
 
-A notebook to write notes while using `rizin`.
+A notebook for binary analysis with rizin. Keep notes, commands, and scripts organized per binary.
 
-If you want to compare it with something similar, you can call it as the rizin equivalent of [jupyter notebook](https://jupyter.org/)
+Requires rizin 0.7.0 or later.
 
-## Requirements
+## What it does
 
-Requires at least rizin version `0.2.0`
+Each notebook **page** is tied to one binary. It stores the binary itself, its SHA-256 hash,
+and a list of **cells**:
 
-## Screenshot
+- **command cells** - a rizin command and its output
+- **script cells** - a JavaScript snippet run on the server against a rizin pipe
+- **markdown cells** - freeform notes
 
-![rizin-notebook](https://raw.githubusercontent.com/rizinorg/rizin-notebook/master/.rizin-notebook.png)
+Pages are stored as individual `.rznb` files (SQLite databases) in `~/.rizin-notebook/`.
+They can be exported and imported as single self-contained files.
 
-## Building
+## Components
+
+- **Go server** (`rizin-notebook`) - the main application. Serves a web UI, exposes a
+  protobuf + JSON REST API, stores everything in per-page `.rznb` SQLite files.
+- **rizin-notebook-plugin** - a rizin core plugin (C). Adds `NB` commands to rizin so you
+  can interact with the notebook from the rizin shell.
+- **cutter-notebook-plugin** - a Cutter plugin (C++/Qt6). Adds a Plugins -> Notebook dock
+  and menu to Cutter.
+
+The plugins are optional. The Go server works standalone with just a browser.
+
+## Compatibility note
+
+The Go server is platform-independent. The plugins depend on the Rizin version they are
+built against.
+
+If standalone rizin and Cutter ship different Rizin versions on your machine, build
+`rz_notebook` once for each. Both builds can talk to the same server and share the same
+`.rznb` data.
+
+Simple rule:
+
+- one server
+- one `rz_notebook` build per Rizin version in use
+- one Cutter plugin if you want the Cutter dock
+
+## Screenshots
+
+Project screenshots are organized under `docs/images/`.
+
+### Web UI
+
+<figure>
+  <img src="docs/images/web-homepage.png" alt="Rizin Notebook" width="100%" />
+  <figcaption><em>Figure 1. Homepage view (with cell & scope based search, supporting multiple modes.)</em></figcaption>
+</figure>
+
+<figure>
+  <img src="docs/images/web-settings.png" alt="Rizin Notebook settings page" width="100%" />
+  <figcaption><em>Figure 2. Settings page for environment configuration, keyboard shortcuts, and server-side behavior.</em></figcaption>
+</figure>
+
+<figure>
+  <img src="docs/images/web-autocomplete.png" alt="Autocomplete suggestions for Rizin commands in the notebook web UI" width="100%" />
+  <figcaption><em>Figure 3. Command autocomplete in the web console, helping discover and complete Rizin commands quickly.</em></figcaption>
+</figure>
+
+<figure>
+  <img src="docs/images/web-command-help.png" alt="Command search and help modal in the notebook web UI" width="100%" />
+  <figcaption><em>Figure 4. Built-in command help and search modal for exploring command descriptions and arguments.</em></figcaption>
+</figure>
+
+### Plugin Integration
+
+<figure>
+  <img src="docs/images/rizin-plugin.png" alt="Rizin core plugin integration for Rizin Notebook" width="100%" />
+  <figcaption><em>Figure 5. Rizin core plugin integration, enabling notebook interaction directly from the Rizin shell.</em></figcaption>
+</figure>
+
+<figure>
+  <img src="docs/images/cutter-plugin-1.png" alt="Cutter plugin integration screenshot 1" width="100%" />
+  <figcaption><em>Figure 6. Cutter plugin integration view showing the notebook experience inside the Cutter interface.</em></figcaption>
+</figure>
+
+<figure>
+  <img src="docs/images/cutter-plugin-2.png" alt="Cutter plugin integration screenshot 2" width="100%" />
+  <figcaption><em>Figure 7. Additional Cutter plugin workflow view demonstrating possible notebook usage(s).</em></figcaption>
+</figure>
+
+## Building the server
+
+```bash
+go build -o rizin-notebook .
+```
+
+Embed the version string during release builds:
+
+```bash
+go build -ldflags "-X main.NBVERSION=$(git rev-parse --short HEAD)" -o rizin-notebook .
+```
+
+## Running
 
 ```bash
-go build -ldflags "-X main.NBVERSION=$(git rev-list -1 HEAD)"
-```
+./rizin-notebook
+```
+
+Opens at `http://127.0.0.1:8000/` by default.
+
+Flags:
+
+```
+-bind 127.0.0.1:8000    address and port to listen on
+-root /                  URL path prefix
+-notebook /path/to/data  data directory (default: ~/.rizin-notebook)
+-debug-assets /path      load templates from disk instead of embedded
+-debug                   enable HTTP request logs
+```
+
+Set `RIZIN_PATH` to override the rizin binary path used for pipe execution.
+
+## Building the rizin plugin
+
+See [rizin-notebook-plugin/README.md](rizin-notebook-plugin/README.md).
+
+## Building the Cutter plugin
+
+See [cutter-notebook-plugin/README.md](cutter-notebook-plugin/README.md).
+
+If Cutter ships its own embedded Rizin, the `rz_notebook` plugin loaded by Cutter must be
+built against that same bundled Rizin version.
+
+## Data storage
+
+Each page is a `.rznb` file in the data directory. It is a SQLite database containing:
+
+- page metadata (title, original filename, binary storage key, SHA-256 hash)
+- cells (type, content, output, timestamps)
+- the binary blob itself
+- per-page config (key/value)
+
+The server maintains a `catalog.db` index for fast listing across all pages.
+
+On first run the server automatically migrates any pages from an older monolithic
+`notebook.db` format into the per-page `.rznb` layout.
+
+## API
+
+All `NB` plugin commands use the protobuf API (`Content-Type: application/x-protobuf`).
+The schema is in `proto/notebook.proto`.
+
+A parallel JSON API at `/api/v1/json/...` is used by the Cutter plugin and the browser UI.