jusi 0.1.0__tar.gz

jusi-0.1.0/.gitignore

@@ -0,0 +1,32 @@
+.local/
+
+# Python bytecode and caches
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Virtual environments
+.venv/
+venv/
+venv1/
+venv2/
+env/
+ENV/
+
+# Build artifacts
+build/
+dist/
+*.egg-info/
+.eggs/
+Dockerfile
+
+# Test and tooling caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+.coverage.*
+htmlcov/
+
+# OS/editor noise
+.DS_Store

jusi-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,46 @@
+# Contributing
+
+## Development Environment
+
+Use an editable install in a virtual environment.
+
+Example:
+
+```sh
+python -m venv .venv
+. .venv/bin/activate
+python -m pip install -e .
+```
+
+An editable install is the preferred workflow because bundled plugins such as
+`jusi_vd` are discovered through installed package metadata.
+
+## Running Tests
+
+Run the backend test suite through the active environment.
+
+Example:
+
+```sh
+python -m unittest
+```
+
+For focused work, run only the affected test modules.
+
+## Documentation
+
+Public-facing docs should:
+
+- describe the current supported contract
+- avoid local repository path references
+- avoid historical or migration framing unless strictly necessary
+- treat the editor side as a regular Vim/Neovim plugin rather than a local sibling checkout
+
+## Repository Scope
+
+This repository is the backend component.
+
+Plugin-specific behavior that does not belong in core should live in:
+
+- a bundled first-party package when it is part of the supported base experience
+- a separate plugin package/repository when it is not core backend functionality

jusi-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 notawhaleble
+
+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.

jusi-0.1.0/PKG-INFO

@@ -0,0 +1,136 @@
+Metadata-Version: 2.4
+Name: jusi
+Version: 0.1.0
+Summary: Standalone backend for Jusivim notebook execution
+Project-URL: Homepage, https://github.com/notawhaleble/jusi
+Project-URL: Repository, https://github.com/notawhaleble/jusi
+Project-URL: Issues, https://github.com/notawhaleble/jusi/issues
+Author: OpenAI Codex
+Author-email: notawhaleble <ponival@gmail.com>
+Maintainer-email: notawhaleble <ponival@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2024 notawhaleble
+        
+        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.
+License-File: LICENSE
+Keywords: jupyter,neovim,notebook,vim
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Text Editors
+Requires-Python: >=3.9
+Requires-Dist: ipykernel<7,>=6
+Requires-Dist: jupyter-client<9,>=8
+Requires-Dist: visidata<4,>=3
+Description-Content-Type: text/markdown
+
+# Jusi
+
+Jusi is the Python backend for notebook-style execution used by the `jusivim` Vim/Neovim plugin.
+
+It is responsible for:
+
+- kernel lifecycle management
+- notebook execution coordination
+- per-cell client lifecycle
+- plugin handler supervision
+- protocol events and transport metadata for the editor side
+
+Jusi is designed as part of a two-component system:
+
+- `jusivim` editor plugin
+- Jusi backend
+
+The backend may run locally or remotely depending on the selected session target.
+
+## Entrypoints
+
+Primary editor-facing entrypoint:
+
+- backend root process: `python -m jusi`
+
+Internal/support entrypoints used by the backend and `jusivim`:
+
+- native terminal attach: `python -m jusi client-process terminal-attach`
+- plugin runtime starter: `python -m jusi plugin-runtime`
+- transcript runtime entrypoint: `python -m jusi client-runtime`
+
+Normal usage is through `jusivim`, which starts and talks to the backend over the Jusi protocol.
+
+## Protocol Features
+
+The backend protocol supports:
+
+- session start and attach
+- cell execution
+- interrupt and input reply
+- disconnect and reconnect
+- client inspection and shutdown
+- structured handler messaging for plugin follow-up and completion
+- native terminal transport advertisement for interactive handlers
+
+Session metadata may also include:
+
+- `plugin_specs`
+  - editor-facing presentation defaults keyed by magic name
+- `palette`
+  - editor-facing plugin creation metadata keyed by magic name
+
+Cell metadata may include:
+
+- `presentation`
+  - authoritative post-handoff presentation metadata for an executed cell
+- `runtime_mode`
+  - backend-owned runtime mode such as `transcript` or `handler`
+
+## Repository Layout
+
+- `src/jusi/domain/`
+  - core models and policies
+- `src/jusi/application/`
+  - use cases and service interfaces
+- `src/jusi/infrastructure/`
+  - Jupyter/runtime integration and process management
+- `src/jusi/interfaces/`
+  - protocol parsing and server entrypoints
+- `src/jusi_vd/`
+  - bundled first-party `%%vd` plugin
+- `docs/`
+  - protocol and architecture reference
+- `tests/`
+  - backend test suite
+
+## Documentation
+
+- [Protocol](docs/protocol.md)
+- [Session Lifecycle](docs/session-lifecycle.md)
+- [Plugin Contract](docs/plugins.md)
+- [Architecture](docs/architecture.md)
+- [Backend Map](docs/backend-map.md)
+
+## Contributing
+
+Development workflow and contributor notes live in [CONTRIBUTING.md](CONTRIBUTING.md).

jusi-0.1.0/README.md

@@ -0,0 +1,87 @@
+# Jusi
+
+Jusi is the Python backend for notebook-style execution used by the `jusivim` Vim/Neovim plugin.
+
+It is responsible for:
+
+- kernel lifecycle management
+- notebook execution coordination
+- per-cell client lifecycle
+- plugin handler supervision
+- protocol events and transport metadata for the editor side
+
+Jusi is designed as part of a two-component system:
+
+- `jusivim` editor plugin
+- Jusi backend
+
+The backend may run locally or remotely depending on the selected session target.
+
+## Entrypoints
+
+Primary editor-facing entrypoint:
+
+- backend root process: `python -m jusi`
+
+Internal/support entrypoints used by the backend and `jusivim`:
+
+- native terminal attach: `python -m jusi client-process terminal-attach`
+- plugin runtime starter: `python -m jusi plugin-runtime`
+- transcript runtime entrypoint: `python -m jusi client-runtime`
+
+Normal usage is through `jusivim`, which starts and talks to the backend over the Jusi protocol.
+
+## Protocol Features
+
+The backend protocol supports:
+
+- session start and attach
+- cell execution
+- interrupt and input reply
+- disconnect and reconnect
+- client inspection and shutdown
+- structured handler messaging for plugin follow-up and completion
+- native terminal transport advertisement for interactive handlers
+
+Session metadata may also include:
+
+- `plugin_specs`
+  - editor-facing presentation defaults keyed by magic name
+- `palette`
+  - editor-facing plugin creation metadata keyed by magic name
+
+Cell metadata may include:
+
+- `presentation`
+  - authoritative post-handoff presentation metadata for an executed cell
+- `runtime_mode`
+  - backend-owned runtime mode such as `transcript` or `handler`
+
+## Repository Layout
+
+- `src/jusi/domain/`
+  - core models and policies
+- `src/jusi/application/`
+  - use cases and service interfaces
+- `src/jusi/infrastructure/`
+  - Jupyter/runtime integration and process management
+- `src/jusi/interfaces/`
+  - protocol parsing and server entrypoints
+- `src/jusi_vd/`
+  - bundled first-party `%%vd` plugin
+- `docs/`
+  - protocol and architecture reference
+- `tests/`
+  - backend test suite
+
+## Documentation
+
+- [Protocol](docs/protocol.md)
+- [Session Lifecycle](docs/session-lifecycle.md)
+- [Plugin Contract](docs/plugins.md)
+- [Architecture](docs/architecture.md)
+- [Backend Map](docs/backend-map.md)
+
+## Contributing
+
+Development workflow and contributor notes live in [CONTRIBUTING.md](CONTRIBUTING.md).

jusi-0.1.0/docs/architecture.md

@@ -0,0 +1,205 @@
+# Jusi Backend Architecture
+
+## Goal
+
+Jusi is the standalone backend process for notebook execution used by the `jusivim` editor plugin.
+
+## Design Principles
+
+- backend domain logic must not depend on Vim rendering details
+- transport is an adapter concern
+- state transitions must be explicit and observable
+- protocol must stay stable enough for editor/backend coordination
+- deployment is conceptually two-component:
+  - `jusivim` editor plugin
+  - Jusi backend
+
+## Deployment Direction
+
+- the editor plugin starts the backend
+- backend is not treated as a separately user-managed daemon in the normal workflow
+- backend may run locally or remotely depending on workflow
+- remote support does not require a third mandatory user-facing helper component
+
+## Runtime Vocabulary
+
+Use these terms consistently:
+
+- `backend root process`
+  - the main `jusi` process started by the editor plugin
+  - entrypoint: `python -m jusi`
+- `session runtime state`
+  - in-memory supervision state held by the backend root process for the session
+  - tracks live per-session resources rather than acting as a multi-session registry
+- `client runtime`
+  - a backend runtime entrypoint used for transcript-host compatibility paths
+  - entrypoint: `python -m jusi client-runtime`
+  - normal notebook execution uses backend-owned in-process transcript state rather than a dedicated client-runtime child
+- `kernel handle`
+  - the execution-side resource for the session
+  - may be a managed child process, an attached external connection, or another runtime handle
+
+The backend-side single-session structure is not a `registry`.
+That word suggests one process indexing many independent session records, which is not the backend shape here.
+
+## Session Model
+
+Backend core keeps explicit session `target` and nothing more in the durable session record:
+
+- `source`
+- `alias`
+- `kind`
+- `value`
+- `config`
+
+Interpretation:
+
+- `target` describes what session/kernel environment the backend starts or attaches to
+- backend residence is an editor-plugin transport concern
+- sessions are durable/reconnectable by default
+- one backend root process supervises one durable session record
+- that same root process may also supervise multiple child client runtimes for that session
+- the editor plugin may keep the real persisted reconnectables list across editor lifetimes
+- durable ids are backend-generated with high-entropy `sess-...` values rather than local counters
+
+## Runtime Slice
+
+- `start_session` starts a backend-owned session
+- `attach_session` exists as a real backend path, but is intentionally narrow:
+  - only `target.kind=connection_file` is executable today
+- managed runtime supports that same narrow attach slice against a real external connection file
+- managed attached sessions use a small connection-file sidecar registry to coordinate stop fanout across peer Jusi root processes
+- that same sidecar carries the shared disconnect timeout deadline for attached peers
+- `execute_cell` allocates the real execution client directly for that cell
+- `disconnect_session` preserves durable session identity as `disconnected`
+- `reconnect_session` restores the durable session linkage without inventing false execution ownership
+- backend root process drives editor-link liveness with backend-issued healthchecks and converts missed replies into the normal disconnect/timeout path
+- session-level health and teardown decisions remain centralized in the backend root process rather than delegated to clients making independent suicide decisions
+
+## Layering
+
+### Domain
+
+Owns:
+
+- session state
+- session target
+- cell execution state
+
+### Application
+
+Owns use cases:
+
+- start session
+- attach session
+- reconnect session
+- execute cell
+- interrupt execution
+- stop session
+
+### Infrastructure
+
+Implements:
+
+- Jupyter/runtime integration
+- process supervision
+- stdio transport loop
+- persistence if introduced later
+
+### Interfaces
+
+Owns:
+
+- protocol parsing
+- event encoding
+- backend entrypoints
+
+## Plugin Direction
+
+Handler/plugin support is not modeled as “just another runtime” or “just a renderer taxonomy”.
+
+- a plugin has at least:
+  - magic command definition
+  - display handler
+- backend core provides:
+  - session/client lifecycle framing
+  - plugin discoverability/loading
+  - status consistency
+  - a structured plugin/editor communication channel
+- plugin display handlers and their runtime processes own:
+  - plugin-specific interaction logic
+  - follow-up/completion semantics
+  - mode transitions, for example VisiData-like navigation into shell-like interaction
+
+See [plugins.md](plugins.md) for the plugin contract.
+
+## Handler Activation
+
+Handler-owned execution follows this model:
+
+- every cell still enters through the Jupyter kernel
+- handler takeover is driven by a kernel-emitted Jusi handoff mime payload
+- backend root process validates that handoff against the registered handler spec
+- backend root process can replace the initial `transcript` client runtime with a `handler` client runtime for that cell/client
+- that handler runtime owns the live plugin handler for that client lifetime
+- normal handler exit maps to cell status `done`
+- unexpected handler death maps to cell status `error`
+- interrupt for handler-owned cells is a structured handler interrupt first
+- follow-up/completion apply only while the handler is alive
+
+Handler startup context is intentionally small:
+
+- `notebook_id`
+- `session_id`
+- `client_id`
+- `cell_id`
+- `handler_id`
+- explicit `magic_name`
+- raw kernel handoff payload and metadata
+
+The backend root process remains the router and supervisor for handler/editor traffic.
+
+## Native Terminal Transport
+
+Interactive terminal-hosted plugins use native terminal attachment rather than notebook-buffer terminal emulation.
+
+- backend root process still owns session and handler lifecycle
+- handler-owned clients use native terminal as the default editor plane
+- when a handler becomes terminal-backed, backend provisions a dedicated terminal client substrate for that `client_id`
+- the editor plugin receives terminal-client metadata from backend and launches a real terminal buffer against that process command
+- terminal transport flows through that native terminal job attachment, not through `handler_message terminal_bytes`
+- `handler_message` stays available for:
+  - follow-up
+  - completion
+  - plugin commands
+  - other control semantics that are not raw terminal traffic
+
+Terminal-backed clients still remain within the normal Jusi client model:
+
+- `session_id`
+- `client_id`
+- optional `handler_id`
+
+The terminal bridge/client runtime maps back to those ids so stop/disconnect/cleanup stay centralized in backend supervision.
+
+Backend advertises terminal-backed clients explicitly through normal client transport metadata:
+
+- cell-owned active client remains a normal backend client
+- backend emits client metadata indicating:
+  - transport kind `native_terminal`
+  - attach command for the terminal buffer
+  - the owning `session_id`
+  - the owning `client_id`
+  - optional `handler_id`
+
+`inspect_client` remains a debug/recovery seam rather than the hot rendering path for native-terminal clients.
+
+## Runtime Ownership
+
+Backend root owns:
+
+- in-process transcript state for plain kernel cells
+- in-process handler control for live handler cells
+
+The only remaining intentional child on the live plugin path is
+`plugin-runtime`.