zbook 0.1.0__tar.gz

zbook-0.1.0/.editorconfig

@@ -0,0 +1,11 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+indent_style = space
+indent_size = 2
+
+[*.py]
+indent_size = 4

zbook-0.1.0/.gitattributes

@@ -0,0 +1 @@
+src/zbook/static/assets/* -diff linguist-generated=true

zbook-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,115 @@
+name: Publish release to PyPI
+
+on:
+  push:
+    tags:
+      - "v[0-9]+.[0-9]+.[0-9]+"
+      - "v[0-9]+.[0-9]+.[0-9]+rc[0-9]+"
+      - "v[0-9]+.[0-9]+.[0-9]+[ab][0-9]+"
+
+concurrency:
+  group: pypi-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  build:
+    name: Build and verify distributions
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - name: Check out source
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        with:
+          enable-cache: false
+          version: "0.12.5"
+
+      - name: Install Node.js
+        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+        with:
+          node-version: 24
+          cache: npm
+          cache-dependency-path: frontend/package-lock.json
+
+      - name: Verify release tag
+        shell: bash
+        run: |
+          package_version="$(uv version --short)"
+          if [[ "v${package_version}" != "${GITHUB_REF_NAME}" ]]; then
+            echo "::error::Tag ${GITHUB_REF_NAME} does not match package version ${package_version}"
+            exit 1
+          fi
+
+      - name: Install Python dependencies
+        run: uv sync --locked --dev
+
+      - name: Check Python
+        run: uv run ruff check .
+
+      - name: Test Python
+        run: uv run pytest -q
+
+      - name: Build web client
+        working-directory: frontend
+        run: |
+          npm ci
+          npm run build
+
+      - name: Verify committed web client
+        shell: bash
+        run: |
+          if [[ -n "$(git status --porcelain -- src/zbook/static)" ]]; then
+            git status --short -- src/zbook/static
+            echo "::error::Frontend build output is not committed"
+            exit 1
+          fi
+
+      - name: Build wheel and source distribution
+        run: uv build --no-sources
+
+      - name: Smoke-test wheel
+        run: uv run --isolated --no-project --with dist/*.whl tests/smoke_test.py
+
+      - name: Smoke-test source distribution
+        run: uv run --isolated --no-project --with dist/*.tar.gz tests/smoke_test.py
+
+      - name: Upload distributions
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: distributions
+          path: dist/
+          if-no-files-found: error
+          retention-days: 7
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/zbook/
+    permissions:
+      id-token: write
+    steps:
+      - name: Install uv
+        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        with:
+          enable-cache: false
+          version: "0.12.5"
+
+      - name: Download distributions
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: distributions
+          path: dist/
+
+      - name: Generate publish attestations
+        uses: astral-sh/attest-action@f589a42a7efb6fe400b4f400de60b4bc90390027 # v0.0.6
+
+      - name: Publish distributions
+        run: uv publish --trusted-publishing always dist/*

zbook-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+.venv/
+tmp/
+.pytest_cache/
+.ruff_cache/
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+frontend/node_modules/

zbook-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zbook contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

zbook-0.1.0/PKG-INFO

@@ -0,0 +1,170 @@
+Metadata-Version: 2.5
+Name: zbook
+Version: 0.1.0
+Summary: A small, keyboard-first notebook with uv and Codex integration
+Project-URL: Homepage, https://github.com/honglu2875/zbook
+Project-URL: Repository, https://github.com/honglu2875/zbook
+Project-URL: Issues, https://github.com/honglu2875/zbook/issues
+Author: honglu2875
+License-Expression: MIT
+License-File: LICENSE
+Keywords: codex,ipython,jupyter,notebook,uv
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Web Environment
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.11
+Requires-Dist: jupyter-server<3,>=2.15
+Requires-Dist: nbformat<6,>=5.10
+Requires-Dist: traitlets<6,>=5.14
+Description-Content-Type: text/markdown
+
+# Zbook
+
+Zbook is an intentionally small, keyboard-first notebook application. It keeps the useful core of Jupyter—real `.ipynb` files, IPython kernels, markdown, rich outputs, and a workspace tree—then adds a first-class local Codex panel and a focused `uv` environment workflow.
+
+The design target is closer to Zed than JupyterLab: flat surfaces, restrained color, minimal persistent chrome, fast keyboard navigation, and no extension ecosystem to carry.
+
+## Working checkpoint
+
+The main notebook loop is functional:
+
+- the file tree is served by Jupyter's Contents API and is rooted at the configured workspace;
+- notebooks can be created, opened in closable tabs, renamed inline by double-clicking a tab, deleted, uploaded, autosaved, and exported as `.ipynb`;
+- open tabs, the active notebook, selected cell, panel visibility, and Vim preference are restored per workspace;
+- `Ctrl/Cmd-P` opens a workspace file picker and `Ctrl/Cmd-Shift-P` opens the command palette;
+- the workspace and Codex panes are draggable, keyboard-resizable, and remember their widths across reloads;
+- refreshing the workspace also reloads the active notebook from disk (after confirming before discarding local unsaved changes);
+- folders can be selected and created, and arbitrary files can be uploaded;
+- code cells execute on a real IPython kernel with streamed text, errors, HTML, and PNG output;
+- Markdown cells render in place; code and Markdown editors have syntax highlighting, bundled JetBrains Mono typography, and optional Vim bindings; the UI and prose use bundled Inter;
+- long outputs can be height-limited from the gutter without shrinking their code, scaled images expand to their native resolution on double-click with two-axis scrolling, and `#@title …` gives a code cell a dedicated title row above its execution gutter and a whole-cell collapse toggle; these view preferences persist per workspace without changing the notebook file;
+- **Run all**, execution counts, interrupt, and keyboard execution commands work;
+- the environment panel lists packages and installs or uninstalls them through serialized `uv` operations;
+- a fresh launch defaults to a scratch uv environment under `/tmp`, prepares `ipykernel`, and removes the scratch environment on shutdown;
+- workspace `.venv` folders are detected and can be selected live; a project folder or uv-venv path can also be entered manually;
+- the Codex panel uses the locally signed-in Codex CLI and ChatGPT subscription—no application API key—and streams turns through Codex App Server;
+- Codex receives optional notebook/cell context and exposes live command/file activity plus any required approvals;
+- Codex gets dedicated read/lock/apply cell tools: the read response advertises the current action inventory, relevant cells become visibly read-only across the full reasoning-and-editing turn, remaining locks release automatically at turn end, and edits are revision-checked, atomic, undoable, and saved without a shell/edit/refresh round trip; source-light reads plus `move_after` and `swap` operations make reordering inexpensive;
+- each Codex cell edit gets an in-notebook review marker and a safe one-step undo until the notebook changes again;
+- the Codex pane reads the installed CLI's model catalog and subscription rate limits, defaults to GPT-5.6-Luna with medium reasoning when available, and provides model/effort pickers, quota refresh, sign-in, and sign-out.
+- Zbook-created Codex threads persist through App Server, are remembered per workspace, and can be resumed from the compact thread switcher with command/file/notebook activity restored and Zbook's private context augmentation kept out of the visible transcript.
+
+This is still a focused checkpoint, not a JupyterLab replacement. Tabs share one workspace kernel and save before switching; non-notebook files are managed but not edited; and Jupyter widgets and arbitrary JavaScript outputs are not supported.
+
+## Architecture
+
+```text
+React + CodeMirror 6
+  ├─ Jupyter Contents / Kernel WebSocket APIs
+  ├─ Zbook package-management API ── uv ── selected .venv
+  └─ Zbook Codex WebSocket ── codex app-server (stdio JSONL)
+       └─ dynamic cell tools ── revision-locked React notebook state
+
+Jupyter Server ExtensionApp
+  ├─ file boundary: configured workspace
+  ├─ kernel: exact <venv>/bin/python
+  └─ static production frontend
+```
+
+Python owns processes, filesystem boundaries, and Jupyter integration. TypeScript owns interaction state and rendering. The selected notebook environment is deliberately separate from the app's own environment so installing a package cannot destabilize the server. Codex runs with workspace-write scope, while commands that need broader filesystem or network access still use the CLI's approval flow. The bridge follows the official [Codex App Server](https://developers.openai.com/codex/app-server) protocol over a private authenticated WebSocket.
+
+## Run the checks
+
+```bash
+uv run ruff check src tests
+uv run pytest -q
+cd frontend && npm run build
+```
+
+## Build the web client
+
+Use Node.js 20.19 or newer:
+
+```bash
+cd frontend
+npm install
+npm run build
+```
+
+The Vite build is emitted into `src/zbook/static/`, where the Python application serves it.
+
+## Install and launch
+
+Build the web client once, then install the local package as a uv tool:
+
+```bash
+uv sync --dev
+cd frontend && npm install && npm run build && cd ..
+uv tool install .
+```
+
+The installed command has a small preflight check and a dedicated launch command:
+
+```bash
+zbook check
+zbook run
+zbook run --workspace-dir /absolute/path/to/workspace
+zbook run --ip 0.0.0.0 --port 8888
+```
+
+`zbook run` uses the current directory as its workspace and listens only on Jupyter's `localhost` default. Binding a wildcard or non-loopback address prints a highlighted security warning: remote clients that obtain access can execute notebook code and reach the selected workspace and Codex. `0.0.0.0` listens on every network interface, though actual reachability still depends on the host firewall and network configuration. Keep Jupyter authentication enabled.
+
+The default kernel environment is a disposable uv venv under `/tmp`; a persistent uv environment can be selected from the environment panel while the app is running.
+
+Jupyter Server options go after a `--` passthrough boundary:
+
+```bash
+zbook run --workspace-dir /absolute/path/to/workspace --port 8890 -- \
+  --ServerApp.open_browser=False
+```
+
+Startup environment traits can be passed the same way when needed:
+
+```bash
+zbook run --workspace-dir /absolute/path/to/workspace -- \
+  --ZbookApp.venv=/absolute/path/to/project/.venv
+```
+
+For compatibility, Jupyter flags supplied without `--` are still forwarded, but Zbook prints a highlighted warning showing the preferred form. The old direct form (`zbook --ZbookApp.workspace=…`) also remains available with a migration warning. During development, prefix these commands with `uv run`, such as `uv run zbook check`.
+
+## Releasing
+
+Releases are built and published by `.github/workflows/release.yml` through PyPI Trusted Publishing. The PyPI publisher must match the `honglu2875/zbook` repository, the `release.yml` workflow, and the `pypi` GitHub environment.
+
+For the first release, tag the current `0.1.0` commit after configuring the `pypi` environment and pending PyPI publisher:
+
+```bash
+git tag -a v0.1.0 -m "zbook 0.1.0"
+git push origin v0.1.0
+```
+
+For subsequent releases, update the sole package-version source in `pyproject.toml`, review the lockfile, commit, and push the matching tag:
+
+```bash
+uv version 0.1.1
+git add pyproject.toml uv.lock
+git commit -m "Release 0.1.1"
+git tag -a v0.1.1 -m "zbook 0.1.1"
+git push origin main v0.1.1
+```
+
+The workflow rejects a tag that does not match the package version, rebuilds and verifies the committed web client, tests both distribution formats in isolated environments, and grants the publishing credential only to the final PyPI job. Published PyPI versions cannot be replaced; use a new version for every changed release.
+
+## Notebook key model
+
+- `Shift-Escape` leaves an editor and enters notebook navigation mode.
+- `j` / `k` or the arrow keys move between cells in navigation mode.
+- `Enter` or `i` edits the selected cell.
+- `a` inserts a code cell above; `b` or `o` inserts one below. Hover or keyboard-focus the space between cells to choose Code or Markdown explicitly.
+- `Ctrl-Enter` runs in place, `Shift-Enter` runs and advances, and `Alt-Enter` runs and inserts.
+- Vim bindings can be toggled from the status bar. Vim receives its keymap before the standard CodeMirror keymaps.
+
+This two-level model avoids the classic conflict between Vim's modes and notebook-level commands: notebook navigation is a separate outer mode, and Vim operates only inside the active editor.
+
+## License
+
+Zbook is released under the [MIT License](LICENSE). The bundled Inter and JetBrains Mono fonts remain under the SIL Open Font License 1.1; their [notices](frontend/public/font-licenses.txt) ship with the frontend.

zbook-0.1.0/README.md

@@ -0,0 +1,146 @@
+# Zbook
+
+Zbook is an intentionally small, keyboard-first notebook application. It keeps the useful core of Jupyter—real `.ipynb` files, IPython kernels, markdown, rich outputs, and a workspace tree—then adds a first-class local Codex panel and a focused `uv` environment workflow.
+
+The design target is closer to Zed than JupyterLab: flat surfaces, restrained color, minimal persistent chrome, fast keyboard navigation, and no extension ecosystem to carry.
+
+## Working checkpoint
+
+The main notebook loop is functional:
+
+- the file tree is served by Jupyter's Contents API and is rooted at the configured workspace;
+- notebooks can be created, opened in closable tabs, renamed inline by double-clicking a tab, deleted, uploaded, autosaved, and exported as `.ipynb`;
+- open tabs, the active notebook, selected cell, panel visibility, and Vim preference are restored per workspace;
+- `Ctrl/Cmd-P` opens a workspace file picker and `Ctrl/Cmd-Shift-P` opens the command palette;
+- the workspace and Codex panes are draggable, keyboard-resizable, and remember their widths across reloads;
+- refreshing the workspace also reloads the active notebook from disk (after confirming before discarding local unsaved changes);
+- folders can be selected and created, and arbitrary files can be uploaded;
+- code cells execute on a real IPython kernel with streamed text, errors, HTML, and PNG output;
+- Markdown cells render in place; code and Markdown editors have syntax highlighting, bundled JetBrains Mono typography, and optional Vim bindings; the UI and prose use bundled Inter;
+- long outputs can be height-limited from the gutter without shrinking their code, scaled images expand to their native resolution on double-click with two-axis scrolling, and `#@title …` gives a code cell a dedicated title row above its execution gutter and a whole-cell collapse toggle; these view preferences persist per workspace without changing the notebook file;
+- **Run all**, execution counts, interrupt, and keyboard execution commands work;
+- the environment panel lists packages and installs or uninstalls them through serialized `uv` operations;
+- a fresh launch defaults to a scratch uv environment under `/tmp`, prepares `ipykernel`, and removes the scratch environment on shutdown;
+- workspace `.venv` folders are detected and can be selected live; a project folder or uv-venv path can also be entered manually;
+- the Codex panel uses the locally signed-in Codex CLI and ChatGPT subscription—no application API key—and streams turns through Codex App Server;
+- Codex receives optional notebook/cell context and exposes live command/file activity plus any required approvals;
+- Codex gets dedicated read/lock/apply cell tools: the read response advertises the current action inventory, relevant cells become visibly read-only across the full reasoning-and-editing turn, remaining locks release automatically at turn end, and edits are revision-checked, atomic, undoable, and saved without a shell/edit/refresh round trip; source-light reads plus `move_after` and `swap` operations make reordering inexpensive;
+- each Codex cell edit gets an in-notebook review marker and a safe one-step undo until the notebook changes again;
+- the Codex pane reads the installed CLI's model catalog and subscription rate limits, defaults to GPT-5.6-Luna with medium reasoning when available, and provides model/effort pickers, quota refresh, sign-in, and sign-out.
+- Zbook-created Codex threads persist through App Server, are remembered per workspace, and can be resumed from the compact thread switcher with command/file/notebook activity restored and Zbook's private context augmentation kept out of the visible transcript.
+
+This is still a focused checkpoint, not a JupyterLab replacement. Tabs share one workspace kernel and save before switching; non-notebook files are managed but not edited; and Jupyter widgets and arbitrary JavaScript outputs are not supported.
+
+## Architecture
+
+```text
+React + CodeMirror 6
+  ├─ Jupyter Contents / Kernel WebSocket APIs
+  ├─ Zbook package-management API ── uv ── selected .venv
+  └─ Zbook Codex WebSocket ── codex app-server (stdio JSONL)
+       └─ dynamic cell tools ── revision-locked React notebook state
+
+Jupyter Server ExtensionApp
+  ├─ file boundary: configured workspace
+  ├─ kernel: exact <venv>/bin/python
+  └─ static production frontend
+```
+
+Python owns processes, filesystem boundaries, and Jupyter integration. TypeScript owns interaction state and rendering. The selected notebook environment is deliberately separate from the app's own environment so installing a package cannot destabilize the server. Codex runs with workspace-write scope, while commands that need broader filesystem or network access still use the CLI's approval flow. The bridge follows the official [Codex App Server](https://developers.openai.com/codex/app-server) protocol over a private authenticated WebSocket.
+
+## Run the checks
+
+```bash
+uv run ruff check src tests
+uv run pytest -q
+cd frontend && npm run build
+```
+
+## Build the web client
+
+Use Node.js 20.19 or newer:
+
+```bash
+cd frontend
+npm install
+npm run build
+```
+
+The Vite build is emitted into `src/zbook/static/`, where the Python application serves it.
+
+## Install and launch
+
+Build the web client once, then install the local package as a uv tool:
+
+```bash
+uv sync --dev
+cd frontend && npm install && npm run build && cd ..
+uv tool install .
+```
+
+The installed command has a small preflight check and a dedicated launch command:
+
+```bash
+zbook check
+zbook run
+zbook run --workspace-dir /absolute/path/to/workspace
+zbook run --ip 0.0.0.0 --port 8888
+```
+
+`zbook run` uses the current directory as its workspace and listens only on Jupyter's `localhost` default. Binding a wildcard or non-loopback address prints a highlighted security warning: remote clients that obtain access can execute notebook code and reach the selected workspace and Codex. `0.0.0.0` listens on every network interface, though actual reachability still depends on the host firewall and network configuration. Keep Jupyter authentication enabled.
+
+The default kernel environment is a disposable uv venv under `/tmp`; a persistent uv environment can be selected from the environment panel while the app is running.
+
+Jupyter Server options go after a `--` passthrough boundary:
+
+```bash
+zbook run --workspace-dir /absolute/path/to/workspace --port 8890 -- \
+  --ServerApp.open_browser=False
+```
+
+Startup environment traits can be passed the same way when needed:
+
+```bash
+zbook run --workspace-dir /absolute/path/to/workspace -- \
+  --ZbookApp.venv=/absolute/path/to/project/.venv
+```
+
+For compatibility, Jupyter flags supplied without `--` are still forwarded, but Zbook prints a highlighted warning showing the preferred form. The old direct form (`zbook --ZbookApp.workspace=…`) also remains available with a migration warning. During development, prefix these commands with `uv run`, such as `uv run zbook check`.
+
+## Releasing
+
+Releases are built and published by `.github/workflows/release.yml` through PyPI Trusted Publishing. The PyPI publisher must match the `honglu2875/zbook` repository, the `release.yml` workflow, and the `pypi` GitHub environment.
+
+For the first release, tag the current `0.1.0` commit after configuring the `pypi` environment and pending PyPI publisher:
+
+```bash
+git tag -a v0.1.0 -m "zbook 0.1.0"
+git push origin v0.1.0
+```
+
+For subsequent releases, update the sole package-version source in `pyproject.toml`, review the lockfile, commit, and push the matching tag:
+
+```bash
+uv version 0.1.1
+git add pyproject.toml uv.lock
+git commit -m "Release 0.1.1"
+git tag -a v0.1.1 -m "zbook 0.1.1"
+git push origin main v0.1.1
+```
+
+The workflow rejects a tag that does not match the package version, rebuilds and verifies the committed web client, tests both distribution formats in isolated environments, and grants the publishing credential only to the final PyPI job. Published PyPI versions cannot be replaced; use a new version for every changed release.
+
+## Notebook key model
+
+- `Shift-Escape` leaves an editor and enters notebook navigation mode.
+- `j` / `k` or the arrow keys move between cells in navigation mode.
+- `Enter` or `i` edits the selected cell.
+- `a` inserts a code cell above; `b` or `o` inserts one below. Hover or keyboard-focus the space between cells to choose Code or Markdown explicitly.
+- `Ctrl-Enter` runs in place, `Shift-Enter` runs and advances, and `Alt-Enter` runs and inserts.
+- Vim bindings can be toggled from the status bar. Vim receives its keymap before the standard CodeMirror keymaps.
+
+This two-level model avoids the classic conflict between Vim's modes and notebook-level commands: notebook navigation is a separate outer mode, and Vim operates only inside the active editor.
+
+## License
+
+Zbook is released under the [MIT License](LICENSE). The bundled Inter and JetBrains Mono fonts remain under the SIL Open Font License 1.1; their [notices](frontend/public/font-licenses.txt) ship with the frontend.

zbook-0.1.0/frontend/index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta name="theme-color" content="#17191b" />
+    <title>Zbook</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>