jusi-shell 0.2.0__tar.gz

jusi_shell-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 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_shell-0.2.0/PKG-INFO

@@ -0,0 +1,53 @@
+Metadata-Version: 2.4
+Name: jusi-shell
+Version: 0.2.0
+Summary: Shell plugin for Jusi
+Author: Jusi contributors
+License: MIT License
+        
+        Copyright (c) 2025 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
+Requires-Python: >=3.9
+Requires-Dist: jusi<2,>=1.0
+Description-Content-Type: text/markdown
+
+# jusi-shell
+
+An interactive shell plugin for Jusi 1.0.
+
+- `%%shell` starts the configured/default shell.
+- `%%shell bash` selects a shell executable.
+- `%%shell --cwd PATH` (or `-C PATH`) starts in an optional working directory.
+- Follow-up cells are sent literally to the same live shell.
+- Path completion follows the shell's current directory and uses explicit Jusi
+  1.0 replacement ranges. Absolute input produces absolute completion text;
+  relative input stays relative.
+- `jusi-open PATH` sends the target-side file contents to the owning editor.
+  The legacy `-t`/`--tab` spelling remains accepted, but Jusi 1.0 owns the
+  destination window rather than exposing split/tab placement to plugins.
+
+Configuration may select a default executable:
+
+```json
+{"shell": {"default": "zsh"}}
+```
+
+The plugin is discovered through the `jusi.plugins.v1` entry-point group.

jusi_shell-0.2.0/README.md

@@ -0,0 +1,22 @@
+# jusi-shell
+
+An interactive shell plugin for Jusi 1.0.
+
+- `%%shell` starts the configured/default shell.
+- `%%shell bash` selects a shell executable.
+- `%%shell --cwd PATH` (or `-C PATH`) starts in an optional working directory.
+- Follow-up cells are sent literally to the same live shell.
+- Path completion follows the shell's current directory and uses explicit Jusi
+  1.0 replacement ranges. Absolute input produces absolute completion text;
+  relative input stays relative.
+- `jusi-open PATH` sends the target-side file contents to the owning editor.
+  The legacy `-t`/`--tab` spelling remains accepted, but Jusi 1.0 owns the
+  destination window rather than exposing split/tab placement to plugins.
+
+Configuration may select a default executable:
+
+```json
+{"shell": {"default": "zsh"}}
+```
+
+The plugin is discovered through the `jusi.plugins.v1` entry-point group.

jusi_shell-0.2.0/pyproject.toml

@@ -0,0 +1,23 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "jusi-shell"
+version = "0.2.0"
+description = "Shell plugin for Jusi"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { file = "LICENSE" }
+authors = [
+  { name = "Jusi contributors" }
+]
+dependencies = [
+  "jusi>=1.0,<2",
+]
+
+[project.entry-points."jusi.plugins.v1"]
+jusi_shell = "jusi_shell.catalog:catalog_entry"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/jusi_shell"]

jusi_shell-0.2.0/src/jusi_shell/__init__.py

@@ -0,0 +1,5 @@
+"""Jusi 1.0 interactive shell plugin."""
+
+__version__ = "0.2.0"
+
+__all__ = ["__version__"]

jusi_shell-0.2.0/src/jusi_shell/application.py

@@ -0,0 +1,354 @@
+from __future__ import annotations
+
+import argparse
+import fcntl
+import json
+import os
+from pathlib import Path
+import pty
+import selectors
+import shlex
+import shutil
+import signal
+import socket
+import struct
+import sys
+import tempfile
+import termios
+import threading
+from typing import Any
+
+
+_INTERACTIVE_SHELLS = {"bash", "dash", "fish", "ksh", "sh", "zsh"}
+
+
+def _winsize(fd: int) -> bytes | None:
+    try:
+        return fcntl.ioctl(fd, termios.TIOCGWINSZ, struct.pack("HHHH", 0, 0, 0, 0))
+    except OSError:
+        return None
+
+
+def _set_winsize(fd: int, value: bytes | None) -> None:
+    if value is not None:
+        fcntl.ioctl(fd, termios.TIOCSWINSZ, value)
+
+
+class ShellApplication:
+    def __init__(self, launch: dict[str, Any], socket_path: str) -> None:
+        self.body = str(launch.get("body", ""))
+        self.requested_shell = str(launch.get("shell", "")).strip()
+        self.socket_path = socket_path
+        self.current_cwd = os.getcwd()
+        self.master_fd = -1
+        self.child_pid = 0
+        self.returncode: int | None = None
+        self.stop_event = threading.Event()
+        self.terminate_requested = threading.Event()
+        self.write_lock = threading.Lock()
+        self.state_lock = threading.Lock()
+        self.server: socket.socket | None = None
+        self.server_thread: threading.Thread | None = None
+        self.state_directory = tempfile.TemporaryDirectory(prefix="jusi-shell-app-")
+        self.saved_terminal: list[Any] | None = None
+
+    def run(self) -> int:
+        self._start_control_server()
+        shell_path, argv, env = self._shell_command()
+        pid, master_fd = pty.fork()
+        if pid == 0:
+            for signum in (signal.SIGINT, signal.SIGQUIT, signal.SIGTERM):
+                signal.signal(signum, signal.SIG_DFL)
+            try:
+                os.execvpe(shell_path, argv, env)
+            except BaseException as exc:
+                os.write(2, f"jusi-shell: {exc}\n".encode("utf-8", "replace"))
+                os._exit(127)
+
+        self.child_pid, self.master_fd = pid, master_fd
+        _set_winsize(master_fd, _winsize(sys.stdin.fileno()))
+        self._install_signal_handlers()
+        self._set_raw_terminal()
+        if self.body.strip():
+            self._send(self.body)
+        try:
+            return self._pump_terminal()
+        finally:
+            self.close()
+
+    def _shell_command(self) -> tuple[str, list[str], dict[str, str]]:
+        requested = self.requested_shell or os.environ.get("SHELL", "").strip() or "/bin/sh"
+        shell_path = shutil.which(requested) if not os.path.isabs(requested) else requested
+        if not shell_path:
+            raise RuntimeError(f"requested shell is not available: {requested}")
+        name = os.path.basename(shell_path)
+        env = os.environ.copy()
+        argv = [shell_path]
+        if name == "bash":
+            argv += ["--rcfile", self._write_bashrc(), "-i"]
+        elif name == "zsh":
+            env["ZDOTDIR"] = self.state_directory.name
+            self._write_zshrc()
+            argv.append("-i")
+        elif name == "fish":
+            argv += ["-i", "-C", self._fish_init()]
+        elif name in _INTERACTIVE_SHELLS:
+            argv.append("-i")
+        return shell_path, argv, env
+
+    def _client_command(self) -> str:
+        code = (
+            "import json,os,socket;"
+            f"s=socket.socket(socket.AF_UNIX);s.connect({self.socket_path!r});"
+            "s.sendall((json.dumps({'type':'cwd','cwd':os.getcwd()})+'\\n').encode());s.close()"
+        )
+        return f"{shlex.quote(sys.executable)} -c {shlex.quote(code)} >/dev/null 2>&1"
+
+    @staticmethod
+    def _open_command() -> str:
+        return f"{shlex.quote(sys.executable)} -m jusi.editor_client"
+
+    def _write_bashrc(self) -> str:
+        path = Path(self.state_directory.name) / "bashrc"
+        path.write_text(
+            "\n".join(
+                [
+                    'if [ -f "$HOME/.bashrc" ]; then . "$HOME/.bashrc"; fi',
+                    'jusi-open() { case "${1-}" in -t|--tab) shift;; esac; [ "$#" -ge 1 ] || return 2; '
+                    + self._open_command()
+                    + ' "$1"; }',
+                    "__jusi_emit_cwd() { " + self._client_command() + "; }",
+                    "case \"${PROMPT_COMMAND-}\" in *__jusi_emit_cwd*) ;; *) PROMPT_COMMAND=\"__jusi_emit_cwd${PROMPT_COMMAND:+;$PROMPT_COMMAND}\";; esac",
+                    "__jusi_emit_cwd",
+                ]
+            )
+            + "\n",
+            encoding="utf-8",
+        )
+        return str(path)
+
+    def _write_zshrc(self) -> None:
+        path = Path(self.state_directory.name) / ".zshrc"
+        path.write_text(
+            "\n".join(
+                [
+                    'if [ -f "$HOME/.zshrc" ]; then . "$HOME/.zshrc"; fi',
+                    'jusi-open() { case "${1-}" in -t|--tab) shift;; esac; [ "$#" -ge 1 ] || return 2; '
+                    + self._open_command()
+                    + ' "$1"; }',
+                    "autoload -Uz add-zsh-hook",
+                    "__jusi_emit_cwd() { " + self._client_command() + "; }",
+                    "add-zsh-hook precmd __jusi_emit_cwd",
+                    "__jusi_emit_cwd",
+                ]
+            )
+            + "\n",
+            encoding="utf-8",
+        )
+
+    def _fish_init(self) -> str:
+        return (
+            "function jusi-open; "
+            "if test (count $argv) -gt 0; and contains -- $argv[1] -t --tab; set -e argv[1]; end; "
+            "test (count $argv) -ge 1; or return 2; "
+            + self._open_command()
+            + " $argv[1]; end; "
+            "function __jusi_emit_cwd --on-event fish_prompt; "
+            + self._client_command()
+            + "; end; __jusi_emit_cwd"
+        )
+
+    def _start_control_server(self) -> None:
+        try:
+            os.unlink(self.socket_path)
+        except FileNotFoundError:
+            pass
+        server = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
+        server.bind(self.socket_path)
+        server.listen()
+        server.settimeout(0.2)
+        self.server = server
+
+        def serve() -> None:
+            while not self.stop_event.is_set():
+                try:
+                    connection, _ = server.accept()
+                except socket.timeout:
+                    continue
+                except OSError:
+                    return
+                with connection:
+                    try:
+                        raw = connection.makefile("rb").readline()
+                        request = json.loads(raw)
+                        response = self._handle_request(request)
+                        connection.sendall(json.dumps(response).encode("utf-8") + b"\n")
+                    except (OSError, ValueError, TypeError, json.JSONDecodeError):
+                        continue
+
+        self.server_thread = threading.Thread(target=serve, name="jusi-shell-control", daemon=True)
+        self.server_thread.start()
+
+    def _handle_request(self, request: object) -> dict[str, Any]:
+        if not isinstance(request, dict):
+            return {"ok": False, "error": "invalid request"}
+        kind = request.get("type")
+        if kind == "cwd":
+            value = str(request.get("cwd", "")).strip()
+            if value:
+                with self.state_lock:
+                    self.current_cwd = value
+            return {"ok": True}
+        if kind == "status":
+            with self.state_lock:
+                cwd = self.current_cwd
+            return {"ok": True, "cwd": cwd}
+        if kind == "followup":
+            if self.returncode is not None:
+                return {"ok": False, "error": "shell has exited"}
+            self._send(str(request.get("body", "")))
+            return {"ok": True}
+        return {"ok": False, "error": f"unsupported request: {kind}"}
+
+    def _send(self, text: str) -> None:
+        data = text.encode("utf-8")
+        if not data.endswith(b"\n"):
+            data += b"\n"
+        with self.write_lock:
+            if self.master_fd < 0:
+                raise OSError("shell terminal is unavailable")
+            os.write(self.master_fd, data)
+
+    def _install_signal_handlers(self) -> None:
+        def resize(*_: object) -> None:
+            try:
+                _set_winsize(self.master_fd, _winsize(sys.stdin.fileno()))
+            except OSError:
+                pass
+
+        def forward(signum: int, _frame: object) -> None:
+            try:
+                os.killpg(self.child_pid, signum)
+            except ProcessLookupError:
+                pass
+
+        def terminate(_signum: int, _frame: object) -> None:
+            self.terminate_requested.set()
+            self.stop_event.set()
+            try:
+                os.killpg(self.child_pid, signal.SIGTERM)
+            except ProcessLookupError:
+                pass
+
+        signal.signal(signal.SIGWINCH, resize)
+        for signum in (signal.SIGINT, signal.SIGQUIT):
+            signal.signal(signum, forward)
+        signal.signal(signal.SIGTERM, terminate)
+
+    def _set_raw_terminal(self) -> None:
+        try:
+            self.saved_terminal = termios.tcgetattr(sys.stdin.fileno())
+            attrs = termios.tcgetattr(sys.stdin.fileno())
+            attrs[0] &= ~(termios.BRKINT | termios.ICRNL | termios.INPCK | termios.ISTRIP | termios.IXON)
+            attrs[1] &= ~termios.OPOST
+            attrs[2] |= termios.CS8
+            attrs[3] &= ~(termios.ECHO | termios.ICANON | termios.IEXTEN | termios.ISIG)
+            attrs[6][termios.VMIN] = 1
+            attrs[6][termios.VTIME] = 0
+            termios.tcsetattr(sys.stdin.fileno(), termios.TCSANOW, attrs)
+        except termios.error:
+            self.saved_terminal = None
+
+    def _pump_terminal(self) -> int:
+        selector = selectors.DefaultSelector()
+        selector.register(self.master_fd, selectors.EVENT_READ, "shell")
+        selector.register(sys.stdin.fileno(), selectors.EVENT_READ, "input")
+        try:
+            while not self.terminate_requested.is_set() and self._poll_child() is None:
+                for key, _ in selector.select(timeout=0.1):
+                    try:
+                        data = os.read(key.fd, 65536)
+                    except OSError:
+                        data = b""
+                    if not data:
+                        if key.data == "input":
+                            selector.unregister(key.fd)
+                        continue
+                    if key.data == "input":
+                        with self.write_lock:
+                            os.write(self.master_fd, data)
+                    else:
+                        os.write(sys.stdout.fileno(), data)
+            if not self.terminate_requested.is_set():
+                while select_ready := selector.select(timeout=0.02):
+                    shell_keys = [key for key, _ in select_ready if key.data == "shell"]
+                    if not shell_keys:
+                        break
+                    try:
+                        data = os.read(self.master_fd, 65536)
+                    except OSError:
+                        break
+                    if not data:
+                        break
+                    os.write(sys.stdout.fileno(), data)
+        finally:
+            selector.close()
+        return int(self.returncode or 0)
+
+    def _poll_child(self) -> int | None:
+        if self.child_pid <= 0 or self.returncode is not None:
+            return self.returncode
+        try:
+            pid, status = os.waitpid(self.child_pid, os.WNOHANG)
+        except ChildProcessError:
+            self.returncode = 0
+            return self.returncode
+        if pid == 0:
+            return None
+        self.returncode = os.waitstatus_to_exitcode(status)
+        return self.returncode
+
+    def close(self) -> None:
+        self.stop_event.set()
+        if self.server is not None:
+            self.server.close()
+        child_running = self.child_pid > 0 and self._poll_child() is None
+        if child_running:
+            try:
+                os.killpg(self.child_pid, signal.SIGHUP)
+            except ProcessLookupError:
+                pass
+        if self.master_fd >= 0:
+            try:
+                os.close(self.master_fd)
+            except OSError:
+                pass
+            self.master_fd = -1
+        if self.saved_terminal is not None:
+            try:
+                termios.tcsetattr(sys.stdin.fileno(), termios.TCSANOW, self.saved_terminal)
+            except termios.error:
+                pass
+        self.state_directory.cleanup()
+
+
+def _read_launch(path: Path) -> dict[str, Any]:
+    try:
+        value = json.loads(path.read_text(encoding="utf-8"))
+    finally:
+        path.unlink(missing_ok=True)
+    if not isinstance(value, dict):
+        raise ValueError("invalid shell launch payload")
+    return value
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="python -m jusi_shell.application")
+    parser.add_argument("launch_path", type=Path)
+    parser.add_argument("socket_path")
+    args = parser.parse_args(argv)
+    return ShellApplication(_read_launch(args.launch_path), args.socket_path).run()
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

jusi_shell-0.2.0/src/jusi_shell/catalog.py

@@ -0,0 +1,23 @@
+"""Discovery-only catalog entry; runtime modules are deliberately not imported."""
+
+from . import __version__
+
+
+def catalog_entry() -> dict[str, object]:
+    return {
+        "plugin_id": "jusi_shell",
+        "plugin_version": __version__,
+        "distribution": "jusi-shell",
+        "families": [
+            {
+                "family_id": "shell",
+                "magic_name": "shell",
+                "capabilities": ["execute", "followup", "complete", "editor_actions"],
+                "presentation": {"syntax": "sh", "indent": "sh"},
+            }
+        ],
+        "kernel_extensions": ["jusi_shell.kernel"],
+        "worker_entry_point": "jusi_shell.worker:create_worker",
+        "media_types": ["text/x-ansi"],
+        "interaction": "terminal_interactive",
+    }

jusi_shell-0.2.0/src/jusi_shell/completion.py

@@ -0,0 +1,55 @@
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Any
+
+
+def _active_word(prefix: str) -> tuple[str, int]:
+    line_start = prefix.rfind("\n") + 1
+    line = prefix[line_start:]
+    index = len(line)
+    while index > 0 and not line[index - 1].isspace():
+        index -= 1
+    return line[index:], line_start + index
+
+
+def complete_paths(payload: dict[str, Any], cwd: str) -> dict[str, list[dict[str, Any]]]:
+    prefix = str(payload.get("prefix", ""))
+    cursor_pos = payload.get("cursor_pos")
+    if not isinstance(cursor_pos, int) or cursor_pos != len(prefix):
+        return {"items": []}
+
+    word, start = _active_word(prefix)
+    line_before_word = prefix[prefix.rfind("\n", 0, start) + 1:start]
+    if not word or ("/" not in word and not line_before_word.strip()):
+        return {"items": []}
+
+    slash = word.rfind("/")
+    typed_parent = word[: slash + 1] if slash >= 0 else ""
+    name_prefix = word[slash + 1:]
+    expanded_parent = Path(os.path.expanduser(typed_parent or "."))
+    search_parent = expanded_parent if expanded_parent.is_absolute() else Path(cwd) / expanded_parent
+
+    items: list[dict[str, Any]] = []
+    try:
+        entries = sorted(search_parent.iterdir(), key=lambda item: item.name.casefold())
+    except OSError:
+        return {"items": []}
+    for entry in entries:
+        if not entry.name.startswith(name_prefix):
+            continue
+        text = typed_parent + entry.name
+        if entry.is_dir():
+            text += "/"
+        items.append(
+            {
+                "text": text,
+                "label": entry.name,
+                "kind": "dir" if entry.is_dir() else "file",
+                "detail": str(entry),
+                "start": start,
+                "end": cursor_pos,
+            }
+        )
+    return {"items": items}

jusi_shell-0.2.0/src/jusi_shell/control.py

@@ -0,0 +1,22 @@
+from __future__ import annotations
+
+import json
+import socket
+from typing import Any
+
+
+def exchange(socket_path: str, request: dict[str, Any], *, timeout: float = 3.0) -> dict[str, Any]:
+    with socket.socket(socket.AF_UNIX, socket.SOCK_STREAM) as connection:
+        connection.settimeout(timeout)
+        connection.connect(socket_path)
+        stream = connection.makefile("rwb")
+        with stream:
+            stream.write(json.dumps(request).encode("utf-8") + b"\n")
+            stream.flush()
+            raw = stream.readline()
+    if not raw:
+        raise ConnectionError("shell application closed the control connection")
+    result = json.loads(raw)
+    if not isinstance(result, dict):
+        raise ValueError("invalid shell application response")
+    return result

jusi_shell-0.2.0/src/jusi_shell/kernel.py

@@ -0,0 +1,73 @@
+from __future__ import annotations
+
+import argparse
+import os
+import shlex
+from typing import Any
+
+from IPython.core.error import UsageError
+
+from . import __version__
+
+
+HANDOFF_MIME = "application/vnd.jusi.handoff.v1+json"
+_runtime_configuration: dict[str, Any] = {}
+
+
+class _ArgumentParser(argparse.ArgumentParser):
+    def error(self, message: str) -> None:  # type: ignore[override]
+        raise UsageError(message)
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = _ArgumentParser(prog="%%shell", add_help=False)
+    parser.add_argument("-C", "--cwd", default="")
+    parser.add_argument("shell_name", nargs="?", default="")
+    return parser
+
+
+def jusi_kernel_adapter_v1() -> dict[str, object]:
+    return {
+        "plugin_id": "jusi_shell",
+        "plugin_version": __version__,
+        "families": [{"family_id": "shell", "magic_name": "shell"}],
+    }
+
+
+def configure_jusi_runtime_v1(configuration: dict[str, Any]) -> None:
+    global _runtime_configuration
+    _runtime_configuration = dict(configuration)
+
+
+def _default_shell() -> str:
+    shell = _runtime_configuration.get("shell")
+    if not isinstance(shell, dict):
+        return ""
+    return str(shell.get("default", shell.get("default_shell", ""))).strip()
+
+
+def load_ipython_extension(ipython: Any) -> None:
+    cell_magics = getattr(getattr(ipython, "magics_manager", None), "magics", {}).get("cell", {})
+    if "shell" in cell_magics:
+        return
+
+    def _jusi_shell_magic(line: str, cell: str) -> None:
+        from IPython.display import display
+
+        args = _parser().parse_args(shlex.split(line))
+        shell_name = str(args.shell_name or "").strip() or _default_shell()
+        cwd = str(args.cwd or "").strip()
+        if cwd:
+            cwd = os.path.abspath(os.path.expanduser(cwd))
+        payload = {
+            "protocol_version": 1,
+            "kind": "plugin.handoff",
+            "plugin_id": "jusi_shell",
+            "plugin_version": __version__,
+            "family_id": "shell",
+            "magic_name": "shell",
+            "payload": {"shell": shell_name, "cwd": cwd, "body": str(cell or "")},
+        }
+        display({HANDOFF_MIME: payload}, raw=True)
+
+    ipython.register_magic_function(_jusi_shell_magic, magic_kind="cell", magic_name="shell")

jusi_shell-0.2.0/src/jusi_shell/worker.py

@@ -0,0 +1,130 @@
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+import shutil
+import sys
+import tempfile
+import time
+from typing import Any
+
+from jusi.plugin_api import OperationRejected, WorkerResult, copy_text, open_text, show_diff, terminal_surface
+
+from .completion import complete_paths
+from .control import exchange
+
+
+def _followup_body(body: str) -> str:
+    """Remove this plugin's cell-magic header from a frontend followup."""
+    first_line, separator, remainder = body.partition("\n")
+    header = first_line.strip()
+    if header == "%%shell" or header.startswith(("%%shell ", "%%shell\t")):
+        return remainder if separator else ""
+    return body
+
+
+class ShellWorker:
+    def __init__(self, context: object) -> None:
+        self.context = context
+        self.runtime_directory: Path | None = None
+        self.socket_path = ""
+        self.cwd = ""
+
+    def handle(self, operation: str, payload: dict[str, Any]) -> WorkerResult:
+        if operation == "execute":
+            return self._execute(payload)
+        if operation == "followup":
+            self._request({"type": "followup", "body": _followup_body(str(payload.get("body", "")))})
+            return WorkerResult({"accepted": True})
+        if operation == "complete":
+            status = self._request({"type": "status"})
+            cwd = str(status.get("cwd", "")).strip() or self.cwd
+            return WorkerResult(complete_paths(payload, cwd))
+        if operation == "editor_action":
+            return self._editor_action(payload)
+        raise OperationRejected(f"Unsupported shell operation: {operation}", reason="unsupported")
+
+    def _execute(self, payload: dict[str, Any]) -> WorkerResult:
+        if self.runtime_directory is not None:
+            raise OperationRejected("Shell client is already initialized", reason="conflict")
+        cwd = str(payload.get("cwd", "")).strip() or os.getcwd()
+        cwd = os.path.abspath(os.path.expanduser(cwd))
+        if not os.path.isdir(cwd):
+            raise OperationRejected(f"Shell working directory does not exist: {cwd}", reason="invalid_request")
+
+        shell_name = str(payload.get("shell", "")).strip()
+        if shell_name and shutil.which(shell_name) is None:
+            raise OperationRejected(f"Requested shell is not available: {shell_name}", reason="invalid_request")
+
+        self.runtime_directory = Path(tempfile.mkdtemp(prefix="jusi-shell-"))
+        self.runtime_directory.chmod(0o700)
+        self.socket_path = str(self.runtime_directory / "control.sock")
+        self.cwd = cwd
+        payload_path = self.runtime_directory / "launch.json"
+        fd = os.open(payload_path, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
+        try:
+            with os.fdopen(fd, "w", encoding="utf-8") as stream:
+                json.dump({"body": str(payload.get("body", "")), "shell": shell_name}, stream)
+        except BaseException:
+            self.close()
+            raise
+
+        return WorkerResult(
+            {"accepted": True, "cwd": cwd},
+            (
+                terminal_surface(
+                    "shell_terminal",
+                    (sys.executable, "-m", "jusi_shell.application", str(payload_path), self.socket_path),
+                    cwd=cwd,
+                    environment_overrides={"TERM": os.environ.get("JUSI_SHELL_TERM", "").strip() or "xterm-256color"},
+                    signal=True,
+                ),
+            ),
+        )
+
+    def _request(self, request: dict[str, Any]) -> dict[str, Any]:
+        if self.runtime_directory is None:
+            raise OperationRejected("Shell client is not initialized", reason="conflict")
+        deadline = time.monotonic() + 3.0
+        while True:
+            try:
+                result = exchange(self.socket_path, request)
+                break
+            except (ConnectionError, FileNotFoundError, OSError, ValueError) as exc:
+                if time.monotonic() >= deadline:
+                    raise OperationRejected("Shell application is not available", reason="conflict") from exc
+                time.sleep(0.02)
+        if not result.get("ok"):
+            raise OperationRejected(str(result.get("error", "Shell request failed")))
+        return result
+
+    @staticmethod
+    def _editor_action(payload: dict[str, Any]) -> WorkerResult:
+        selection = payload.get("selection")
+        if not isinstance(selection, dict):
+            raise OperationRejected("Shell selection is missing", reason="invalid_request")
+        action = str(payload.get("action", ""))
+        if action == "show_diff":
+            before, after = selection.get("before"), selection.get("after")
+            if not isinstance(before, str) or not isinstance(after, str):
+                raise OperationRejected("Shell diff selection requires before and after text", reason="invalid_request")
+            return show_diff(before, after, filetype="sh")
+        text = selection.get("text")
+        if not isinstance(text, str):
+            raise OperationRejected("Shell selection requires text", reason="invalid_request")
+        if action == "copy":
+            return copy_text(text, linewise=bool(selection.get("linewise", False)))
+        if action == "open":
+            return open_text(text, name="shell-selection.sh", filetype="sh")
+        raise OperationRejected(f"Unsupported editor action: {action}", reason="unsupported")
+
+    def close(self) -> None:
+        if self.runtime_directory is not None:
+            shutil.rmtree(self.runtime_directory, ignore_errors=True)
+        self.runtime_directory = None
+        self.socket_path = ""
+
+
+def create_worker(context: object) -> ShellWorker:
+    return ShellWorker(context)

jusi_shell-0.2.0/tests/test_shell_plugin.py

@@ -0,0 +1,224 @@
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+import pty
+import select
+import subprocess
+import sys
+import tempfile
+import time
+import unittest
+from unittest.mock import patch
+
+from jusi.plugin_api import validate_discovered_entry
+from jusi.application.ports import TerminalLaunchSpec
+from jusi.infrastructure.terminal_pty import PosixTerminalBroker
+
+from jusi_shell import __version__
+from jusi_shell.catalog import catalog_entry
+from jusi_shell.completion import complete_paths
+from jusi_shell.control import exchange
+from jusi_shell.kernel import configure_jusi_runtime_v1, jusi_kernel_adapter_v1, load_ipython_extension
+from jusi_shell.worker import ShellWorker, _followup_body
+
+
+class FakeIPython:
+    def __init__(self) -> None:
+        self.magics_manager = type("MagicsManager", (), {"magics": {"cell": {}}})()
+        self.registered: dict[tuple[str, str], object] = {}
+
+    def register_magic_function(self, function, magic_kind: str, magic_name: str) -> None:  # type: ignore[no-untyped-def]
+        self.registered[(magic_kind, magic_name)] = function
+
+
+class CatalogAndKernelTest(unittest.TestCase):
+    def test_catalog_is_a_valid_exact_provider(self) -> None:
+        entry = validate_discovered_entry(
+            catalog_entry(),
+            entry_point_name="jusi_shell",
+            distribution="jusi-shell",
+            distribution_version=__version__,
+        )
+        self.assertEqual(["execute", "followup", "complete", "editor_actions"], entry["families"][0]["capabilities"])
+        self.assertEqual("jusi_shell.worker:create_worker", entry["worker_entry_point"])
+
+    def test_kernel_adapter_matches_catalog(self) -> None:
+        self.assertEqual(
+            {
+                "plugin_id": "jusi_shell",
+                "plugin_version": __version__,
+                "families": [{"family_id": "shell", "magic_name": "shell"}],
+            },
+            jusi_kernel_adapter_v1(),
+        )
+
+    def test_magic_accepts_shell_and_working_directory(self) -> None:
+        captured: dict[str, object] = {}
+
+        def display(value, *, raw=False):  # type: ignore[no-untyped-def]
+            captured.update(value)
+            captured["raw"] = raw
+
+        configure_jusi_runtime_v1({"shell": {"default": "zsh"}})
+        ipython = FakeIPython()
+        with tempfile.TemporaryDirectory() as directory:
+            with patch("IPython.display.display", display):
+                load_ipython_extension(ipython)
+                magic = ipython.registered[("cell", "shell")]
+                magic(f"--cwd {directory}", "pwd")  # type: ignore[operator]
+
+            handoff = captured["application/vnd.jusi.handoff.v1+json"]
+            self.assertTrue(captured["raw"])
+            self.assertEqual("plugin.handoff", handoff["kind"])
+            self.assertEqual("zsh", handoff["payload"]["shell"])
+            self.assertEqual(directory, handoff["payload"]["cwd"])
+            self.assertEqual("pwd", handoff["payload"]["body"])
+
+
+class CompletionTest(unittest.TestCase):
+    def test_absolute_path_stays_absolute(self) -> None:
+        with tempfile.TemporaryDirectory() as directory:
+            Path(directory, "alpha dir").mkdir()
+            prefix = f"cat {directory}/al"
+            result = complete_paths({"body": prefix + "suffix", "prefix": prefix, "cursor_pos": len(prefix)}, "/")
+            (item,) = result["items"]
+            self.assertEqual(f"{directory}/alpha dir/", item["text"])
+            self.assertTrue(item["text"].startswith("/"))
+            self.assertEqual(len("cat "), item["start"])
+            self.assertEqual(len(prefix), item["end"])
+
+    def test_relative_multiline_path_uses_unicode_codepoint_range(self) -> None:
+        with tempfile.TemporaryDirectory() as directory:
+            Path(directory, "δelta.txt").touch()
+            prefix = "echo α\ncat δ"
+            result = complete_paths({"prefix": prefix, "cursor_pos": len(prefix)}, directory)
+            (item,) = result["items"]
+            self.assertEqual("δelta.txt", item["text"])
+            self.assertEqual(prefix.rfind("δ"), item["start"])
+            self.assertEqual(len(prefix), item["end"])
+
+    def test_empty_and_command_prefixes_do_not_offer_paths(self) -> None:
+        self.assertEqual([], complete_paths({"prefix": "", "cursor_pos": 0}, "/")["items"])
+        self.assertEqual([], complete_paths({"prefix": "ec", "cursor_pos": 2}, "/")["items"])
+
+
+class WorkerTest(unittest.TestCase):
+    def test_followup_removes_its_magic_header(self) -> None:
+        worker = ShellWorker(object())
+        with patch.object(worker, "_request") as request:
+            result = worker.handle("followup", {"body": "%%shell --cwd /tmp/example\nls"})
+
+        self.assertTrue(result.result["accepted"])
+        request.assert_called_once_with({"type": "followup", "body": "ls"})
+
+    def test_followup_header_detection_is_exact(self) -> None:
+        self.assertEqual("pwd\n", _followup_body("  %%shell\t--cwd /tmp\npwd\n"))
+        self.assertEqual("%%shellish\nls", _followup_body("%%shellish\nls"))
+
+    def test_execute_returns_one_terminal_surface_with_requested_cwd(self) -> None:
+        worker = ShellWorker(object())
+        with tempfile.TemporaryDirectory() as directory:
+            result = worker.handle("execute", {"shell": "sh", "cwd": directory, "body": "pwd"})
+            self.assertTrue(result.result["accepted"])
+            self.assertEqual(directory, result.result["cwd"])
+            (surface,) = result.core_requests
+            self.assertEqual("shell_terminal", surface.request_id)
+            self.assertEqual(directory, surface.cwd)
+            self.assertEqual(("input", "resize", "signal"), surface.capabilities)
+        worker.close()
+
+    def test_recoverable_bad_cwd_does_not_initialize_worker(self) -> None:
+        from jusi.plugin_api import OperationRejected
+
+        worker = ShellWorker(object())
+        with self.assertRaises(OperationRejected):
+            worker.handle("execute", {"cwd": "/definitely/not/a/jusi-shell-directory"})
+        self.assertIsNone(worker.runtime_directory)
+
+    def test_editor_actions_export_content_not_paths(self) -> None:
+        worker = ShellWorker(object())
+        copied = worker.handle("editor_action", {"action": "copy", "selection": {"text": "/target/file"}})
+        opened = worker.handle("editor_action", {"action": "open", "selection": {"text": "echo ok\n"}})
+        self.assertEqual("/target/file", copied.result["text"])
+        self.assertEqual("echo ok\n", opened.result["text"])
+        self.assertEqual("shell-selection.sh", opened.result["name"])
+
+
+class ApplicationProcessTest(unittest.TestCase):
+    def test_real_application_accepts_followup_over_its_control_socket(self) -> None:
+        with tempfile.TemporaryDirectory() as directory:
+            launch_path = Path(directory, "launch.json")
+            socket_path = str(Path(directory, "control.sock"))
+            launch_path.write_text(json.dumps({"shell": "sh", "body": ""}), encoding="utf-8")
+            master, slave = pty.openpty()
+            env = os.environ.copy()
+            source = str(Path(__file__).resolve().parents[1] / "src")
+            env["PYTHONPATH"] = source + os.pathsep + env.get("PYTHONPATH", "")
+            process = subprocess.Popen(
+                [sys.executable, "-m", "jusi_shell.application", str(launch_path), socket_path],
+                stdin=slave,
+                stdout=slave,
+                stderr=slave,
+                cwd=directory,
+                env=env,
+                close_fds=True,
+            )
+            os.close(slave)
+            try:
+                deadline = time.monotonic() + 5
+                while not os.path.exists(socket_path) and time.monotonic() < deadline:
+                    time.sleep(0.02)
+                self.assertTrue(os.path.exists(socket_path))
+                self.assertEqual(os.path.realpath(directory), os.path.realpath(exchange(socket_path, {"type": "status"})["cwd"]))
+                self.assertTrue(exchange(socket_path, {"type": "followup", "body": "printf JUSI_OK; exit"})["ok"])
+                output = b""
+                while process.poll() is None and time.monotonic() < deadline:
+                    ready, _, _ = select.select([master], [], [], 0.1)
+                    if ready:
+                        try:
+                            output += os.read(master, 65536)
+                        except OSError:
+                            break
+                process.wait(timeout=2)
+                self.assertIn(b"JUSI_OK", output)
+            finally:
+                if process.poll() is None:
+                    process.terminate()
+                    try:
+                        process.wait(timeout=2)
+                    except subprocess.TimeoutExpired:
+                        process.kill()
+                        process.wait(timeout=2)
+                os.close(master)
+
+    @unittest.skipIf(os.name == "nt", "POSIX terminal lifecycle")
+    def test_core_sigterm_closes_application_without_kill_timeout(self) -> None:
+        with tempfile.TemporaryDirectory() as directory:
+            launch_path = Path(directory, "launch.json")
+            socket_path = str(Path(directory, "control.sock"))
+            launch_path.write_text(json.dumps({"shell": "sh", "body": ""}), encoding="utf-8")
+            source = str(Path(__file__).resolve().parents[1] / "src")
+            spec = TerminalLaunchSpec(
+                argv=(sys.executable, "-m", "jusi_shell.application", str(launch_path), socket_path),
+                cwd=directory,
+                env={"TERM": "xterm-256color", "PYTHONPATH": source},
+            )
+            handle = PosixTerminalBroker().start(spec, rows=24, cols=80)
+            deadline = time.monotonic() + 5
+            while not os.path.exists(socket_path) and time.monotonic() < deadline:
+                time.sleep(0.02)
+            self.assertTrue(os.path.exists(socket_path))
+
+            started = time.monotonic()
+            self.assertEqual("stopped", handle.stop(timeout=2.0))
+            elapsed = time.monotonic() - started
+
+            self.assertLess(elapsed, 1.0)
+            self.assertEqual(0, handle.diagnostics.exit_code)
+            self.assertIsNone(handle.diagnostics.signal)
+
+
+if __name__ == "__main__":
+    unittest.main()