shell-use 0.0.1__tar.gz → 0.0.1b2__tar.gz

shell_use-0.0.1b2/.gitignore

@@ -0,0 +1,6 @@
+__pycache__/
+*.pyc
+build/
+dist/
+*.egg-info/
+.pytest_cache/

shell_use-0.0.1b2/PKG-INFO

@@ -0,0 +1,91 @@
+Metadata-Version: 2.4
+Name: shell-use
+Version: 0.0.1b2
+Summary: Python client for the shell-use terminal daemon
+Project-URL: Homepage, https://github.com/microsoft/shell-use
+Project-URL: Repository, https://github.com/microsoft/shell-use
+Author: Microsoft
+License: MIT
+Keywords: automation,pty,shell-use,terminal,testing,tui
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
+# shell-use (Python)
+
+A Python client for the [`shell-use`](https://github.com/microsoft/shell-use) terminal daemon.
+
+The `shell-use` binary must be on your `PATH` (or point to it with the `SHELL_USE_BIN` environment variable or the `binary=` argument). The client talks to the per-session daemon directly over its local socket (a named pipe on Windows, a Unix socket elsewhere) and starts the daemon automatically.
+
+## Install
+
+```sh
+pip install shell-use
+```
+
+Requires Python 3.8+.
+
+## Quick start
+
+```python
+import asyncio
+from shell_use import ShellUse
+
+async def main():
+    async with ShellUse() as su:
+        await su.open()
+        await su.submit("echo hello")
+        await su.wait_command()
+        await su.expect_text("hello")
+        await su.expect_exit_code(0)
+
+asyncio.run(main())
+```
+
+Drive a full-screen TUI:
+
+```python
+async with ShellUse("vim-session") as su:
+    await su.run("vim", "file.txt")
+    await su.wait_idle()
+    await su.press("i")
+    await su.type("some text")
+    await su.press("Escape", ":", "w", "q", "Enter")
+    await su.wait_exit()
+```
+
+## Errors
+
+Every failure maps to one of the daemon's exit codes:
+
+| Exception | Exit code | Meaning |
+| --- | --- | --- |
+| `ExpectationError` | 1 | an `expect`/`wait` condition was not met |
+| `UsageError` | 2 | invalid argument (e.g. a bad regex) |
+| `NoSessionError` | 3 | no active session |
+| `DaemonError` | 4 | daemon could not be reached or started |
+| `VersionMismatchError` | 4 | the daemon's version differs from this package |
+| `InternalError` | 5 | internal daemon error |
+
+All derive from `ShellUseError`. `wait_*` and `expect_*` raise `ExpectationError` on failure.
+
+On its first call, a client checks that the running daemon's version matches the
+package version and raises `VersionMismatchError` if they differ. Stop the daemon
+(`daemon_stop`) so it restarts with the current binary, or point `SHELL_USE_BIN`
+at a matching one.
+
+## API
+
+`ShellUse(session="default", *, binary=None, home=None)` mirrors the CLI: `open` / `run`, `type` / `write`, `submit`, `press` / `keys`, `mouse.click|move|down|up|drag|scroll`, `resize`, `signal` / `kill`, `state`, `text`, `cells`, `get` (+ `get_command` / `get_output` / `get_exit_code` / `get_cwd` / `get_cursor` / `get_size`), `screenshot`, `wait_text` / `wait_idle` / `wait_command` / `wait_exit`, `expect_text` / `expect_exit_code` / `expect_output` / `expect_snapshot`, and `close`.
+
+Module-level helpers: `sessions()`, `close_all()`, `daemon_status()`, `daemon_stop()`, `get_recording()`.
+
+## Configuration
+
+| Variable | Purpose |
+| --- | --- |
+| `SHELL_USE_BIN` | path to the `shell-use` binary |
+| `SHELL_USE_SESSION` | default session name |
+| `SHELL_USE_HOME` | daemon state directory (sockets, pids) |

shell_use-0.0.1b2/README.md

@@ -0,0 +1,76 @@
+# shell-use (Python)
+
+A Python client for the [`shell-use`](https://github.com/microsoft/shell-use) terminal daemon.
+
+The `shell-use` binary must be on your `PATH` (or point to it with the `SHELL_USE_BIN` environment variable or the `binary=` argument). The client talks to the per-session daemon directly over its local socket (a named pipe on Windows, a Unix socket elsewhere) and starts the daemon automatically.
+
+## Install
+
+```sh
+pip install shell-use
+```
+
+Requires Python 3.8+.
+
+## Quick start
+
+```python
+import asyncio
+from shell_use import ShellUse
+
+async def main():
+    async with ShellUse() as su:
+        await su.open()
+        await su.submit("echo hello")
+        await su.wait_command()
+        await su.expect_text("hello")
+        await su.expect_exit_code(0)
+
+asyncio.run(main())
+```
+
+Drive a full-screen TUI:
+
+```python
+async with ShellUse("vim-session") as su:
+    await su.run("vim", "file.txt")
+    await su.wait_idle()
+    await su.press("i")
+    await su.type("some text")
+    await su.press("Escape", ":", "w", "q", "Enter")
+    await su.wait_exit()
+```
+
+## Errors
+
+Every failure maps to one of the daemon's exit codes:
+
+| Exception | Exit code | Meaning |
+| --- | --- | --- |
+| `ExpectationError` | 1 | an `expect`/`wait` condition was not met |
+| `UsageError` | 2 | invalid argument (e.g. a bad regex) |
+| `NoSessionError` | 3 | no active session |
+| `DaemonError` | 4 | daemon could not be reached or started |
+| `VersionMismatchError` | 4 | the daemon's version differs from this package |
+| `InternalError` | 5 | internal daemon error |
+
+All derive from `ShellUseError`. `wait_*` and `expect_*` raise `ExpectationError` on failure.
+
+On its first call, a client checks that the running daemon's version matches the
+package version and raises `VersionMismatchError` if they differ. Stop the daemon
+(`daemon_stop`) so it restarts with the current binary, or point `SHELL_USE_BIN`
+at a matching one.
+
+## API
+
+`ShellUse(session="default", *, binary=None, home=None)` mirrors the CLI: `open` / `run`, `type` / `write`, `submit`, `press` / `keys`, `mouse.click|move|down|up|drag|scroll`, `resize`, `signal` / `kill`, `state`, `text`, `cells`, `get` (+ `get_command` / `get_output` / `get_exit_code` / `get_cwd` / `get_cursor` / `get_size`), `screenshot`, `wait_text` / `wait_idle` / `wait_command` / `wait_exit`, `expect_text` / `expect_exit_code` / `expect_output` / `expect_snapshot`, and `close`.
+
+Module-level helpers: `sessions()`, `close_all()`, `daemon_status()`, `daemon_stop()`, `get_recording()`.
+
+## Configuration
+
+| Variable | Purpose |
+| --- | --- |
+| `SHELL_USE_BIN` | path to the `shell-use` binary |
+| `SHELL_USE_SESSION` | default session name |
+| `SHELL_USE_HOME` | daemon state directory (sockets, pids) |

shell_use-0.0.1b2/pyproject.toml

@@ -0,0 +1,29 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "shell-use"
+version = "0.0.1-beta.2"
+description = "Python client for the shell-use terminal daemon"
+readme = "README.md"
+requires-python = ">=3.8"
+license = { text = "MIT" }
+authors = [{ name = "Microsoft" }]
+keywords = ["terminal", "pty", "automation", "testing", "tui", "shell-use"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/microsoft/shell-use"
+Repository = "https://github.com/microsoft/shell-use"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/shell_use"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/shell_use", "README.md"]

shell_use-0.0.1b2/src/shell_use/__init__.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+from ._config import VERSION as __version__
+from .client import (
+    ShellUse,
+    close_all,
+    daemon_status,
+    daemon_stop,
+    get_recording,
+    sessions,
+)
+from .errors import (
+    DaemonError,
+    ExpectationError,
+    InternalError,
+    NoSessionError,
+    ShellUseError,
+    UsageError,
+    VersionMismatchError,
+)
+from .types import Cell, State
+
+__all__ = [
+    "ShellUse",
+    "sessions",
+    "close_all",
+    "daemon_status",
+    "daemon_stop",
+    "get_recording",
+    "ShellUseError",
+    "ExpectationError",
+    "UsageError",
+    "NoSessionError",
+    "DaemonError",
+    "VersionMismatchError",
+    "InternalError",
+    "Cell",
+    "State",
+    "__version__",
+]

shell_use-0.0.1b2/src/shell_use/_config.py

@@ -0,0 +1,55 @@
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+from typing import Optional
+
+VERSION = "0.0.1-beta.2"
+
+DEFAULT_COLS = 80
+DEFAULT_ROWS = 30
+
+IS_WINDOWS = sys.platform == "win32"
+
+
+def resolve_session(session: Optional[str]) -> str:
+    return session or os.environ.get("SHELL_USE_SESSION") or "default"
+
+
+def resolve_binary(binary: Optional[str]) -> str:
+    return binary or os.environ.get("SHELL_USE_BIN") or "shell-use"
+
+
+def resolve_home(home: Optional[str]) -> Optional[str]:
+    return home or os.environ.get("SHELL_USE_HOME") or None
+
+
+def home_dir(home: Optional[str]) -> Path:
+    return Path(home) if home else Path.home() / ".shell-use"
+
+
+def socket_path(session: str, home: Optional[str]) -> str:
+    if IS_WINDOWS:
+        return rf"\\.\pipe\shell-use-{session}.sock"
+    return str(home_dir(home) / f"{session}.sock")
+
+
+def _cache_dir() -> Path:
+    if IS_WINDOWS:
+        base = os.environ.get("LOCALAPPDATA")
+        return Path(base) if base else Path.home() / "AppData" / "Local"
+    if sys.platform == "darwin":
+        return Path.home() / "Library" / "Caches"
+    xdg = os.environ.get("XDG_CACHE_HOME")
+    return Path(xdg) if xdg else Path.home() / ".cache"
+
+
+def recording_dir(home: Optional[str]) -> Path:
+    if home:
+        return Path(home) / "recordings"
+    return _cache_dir() / "shell-use"
+
+
+def recording_path(session: str, home: Optional[str]) -> Path:
+    return recording_dir(home) / f"{session}.cast"

shell_use-0.0.1b2/src/shell_use/_protocol.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+from typing import Any, Dict, Iterable, List, Mapping, Optional, Tuple, Union
+
+from .errors import make_error
+
+EnvLike = Union[Mapping[str, str], Iterable[Tuple[str, str]], None]
+
+
+def unwrap(resp: Dict[str, Any]) -> Any:
+    if resp.get("ok"):
+        return resp.get("data")
+    raise make_error(resp.get("kind"), resp.get("message") or "shell-use error")
+
+
+def env_pairs(env: EnvLike) -> List[List[str]]:
+    if env is None:
+        return []
+    items = env.items() if isinstance(env, Mapping) else env
+    return [[str(k), str(v)] for k, v in items]

shell_use-0.0.1b2/src/shell_use/_transport.py

@@ -0,0 +1,104 @@
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+from typing import Any, Dict, Optional, Tuple
+
+from . import _config as cfg
+from .errors import DaemonError
+
+_Streams = Tuple[asyncio.StreamReader, asyncio.StreamWriter]
+
+
+async def _open(session: str, home: Optional[str]) -> _Streams:
+    path = cfg.socket_path(session, home)
+    if cfg.IS_WINDOWS:
+        loop = asyncio.get_running_loop()
+        create = getattr(loop, "create_pipe_connection", None)
+        if create is None:
+            raise DaemonError(
+                "named-pipe client requires the Proactor event loop on Windows "
+                "(the default since Python 3.8)"
+            )
+        reader = asyncio.StreamReader()
+        protocol = asyncio.StreamReaderProtocol(reader)
+        transport, _ = await create(lambda: protocol, path)
+        writer = asyncio.StreamWriter(transport, protocol, reader, loop)
+        return reader, writer
+    return await asyncio.open_unix_connection(path)
+
+
+async def _close(writer: asyncio.StreamWriter) -> None:
+    writer.close()
+    try:
+        await writer.wait_closed()
+    except Exception:
+        pass
+
+
+async def can_connect(session: str, home: Optional[str]) -> bool:
+    try:
+        _, writer = await _open(session, home)
+    except (FileNotFoundError, ConnectionRefusedError, OSError):
+        return False
+    await _close(writer)
+    return True
+
+
+async def ensure_daemon(session: str, home: Optional[str], binary: str) -> None:
+    if await can_connect(session, home):
+        return
+    env = dict(os.environ)
+    if home:
+        env["SHELL_USE_HOME"] = home
+    try:
+        proc = await asyncio.create_subprocess_exec(
+            binary,
+            "--session",
+            session,
+            "daemon",
+            "status",
+            stdout=asyncio.subprocess.DEVNULL,
+            stderr=asyncio.subprocess.DEVNULL,
+            env=env,
+        )
+    except FileNotFoundError:
+        raise DaemonError(
+            f"could not find the '{binary}' binary on PATH; "
+            "set SHELL_USE_BIN or pass binary="
+        )
+    await proc.wait()
+    for _ in range(100):
+        if await can_connect(session, home):
+            return
+        await asyncio.sleep(0.05)
+    raise DaemonError(f"daemon for session '{session}' did not become ready")
+
+
+async def request(
+    session: str,
+    home: Optional[str],
+    binary: str,
+    payload: Dict[str, Any],
+    *,
+    autostart: bool = True,
+) -> Dict[str, Any]:
+    if autostart:
+        await ensure_daemon(session, home, binary)
+    try:
+        reader, writer = await _open(session, home)
+    except (FileNotFoundError, ConnectionRefusedError, OSError) as e:
+        raise DaemonError(f"could not connect to session '{session}': {e}")
+    try:
+        writer.write(json.dumps(payload).encode("utf-8") + b"\n")
+        await writer.drain()
+        line = await reader.readline()
+    finally:
+        await _close(writer)
+    if not line:
+        raise DaemonError("daemon closed the connection without responding")
+    try:
+        return json.loads(line.decode("utf-8"))
+    except json.JSONDecodeError as e:
+        raise DaemonError(f"invalid response from daemon: {e}")

shell_use-0.0.1b2/src/shell_use/client.py

@@ -0,0 +1,378 @@
+from __future__ import annotations
+
+import os
+from typing import Any, Dict, List, Optional
+
+from . import _config as cfg
+from . import _transport as transport
+from ._protocol import EnvLike, env_pairs, unwrap
+from .errors import VersionMismatchError
+from .types import Cell, State
+
+
+def check_version(daemon_version: Optional[str]) -> None:
+    if daemon_version != cfg.VERSION:
+        raise VersionMismatchError(
+            f"shell-use version mismatch: client {cfg.VERSION}, daemon "
+            f"{daemon_version or 'unknown'}. Ensure the shell-use binary matches the "
+            "shell-use package version, or stop the daemon (daemon_stop) so it "
+            "restarts with the current binary."
+        )
+
+
+class _Mouse:
+    def __init__(self, client: "ShellUse") -> None:
+        self._c = client
+
+    async def click(
+        self,
+        x: Optional[int] = None,
+        y: Optional[int] = None,
+        *,
+        on_text: Optional[str] = None,
+        button: int = 0,
+        clicks: int = 1,
+    ) -> None:
+        await self._c.send(
+            {
+                "kind": "mouse",
+                "action": {
+                    "op": "click",
+                    "x": x,
+                    "y": y,
+                    "on_text": on_text,
+                    "button": button,
+                    "clicks": clicks,
+                },
+            }
+        )
+
+    async def move(self, x: int, y: int) -> None:
+        await self._c.send({"kind": "mouse", "action": {"op": "move", "x": x, "y": y}})
+
+    async def down(self, x: int, y: int, *, button: int = 0) -> None:
+        await self._c.send(
+            {"kind": "mouse", "action": {"op": "down", "x": x, "y": y, "button": button}}
+        )
+
+    async def up(self, x: int, y: int, *, button: int = 0) -> None:
+        await self._c.send(
+            {"kind": "mouse", "action": {"op": "up", "x": x, "y": y, "button": button}}
+        )
+
+    async def drag(
+        self, x1: int, y1: int, x2: int, y2: int, *, button: int = 0
+    ) -> None:
+        await self._c.send(
+            {
+                "kind": "mouse",
+                "action": {
+                    "op": "drag",
+                    "x1": x1,
+                    "y1": y1,
+                    "x2": x2,
+                    "y2": y2,
+                    "button": button,
+                },
+            }
+        )
+
+    async def scroll(self, direction: str, *, amount: int = 3) -> None:
+        await self._c.send(
+            {
+                "kind": "mouse",
+                "action": {"op": "scroll", "direction": direction, "amount": amount},
+            }
+        )
+
+
+class ShellUse:
+    def __init__(
+        self,
+        session: Optional[str] = None,
+        *,
+        binary: Optional[str] = None,
+        home: Optional[str] = None,
+    ) -> None:
+        self._session = cfg.resolve_session(session)
+        self._binary = cfg.resolve_binary(binary)
+        self._home = cfg.resolve_home(home)
+        self._version_checked = False
+        self.mouse = _Mouse(self)
+
+    @property
+    def session(self) -> str:
+        return self._session
+
+    async def send(self, payload: Dict[str, Any]) -> Any:
+        await self._check_version()
+        resp = await transport.request(self._session, self._home, self._binary, payload)
+        return unwrap(resp)
+
+    async def _check_version(self) -> None:
+        if self._version_checked:
+            return
+        resp = await transport.request(
+            self._session, self._home, self._binary, {"kind": "status"}
+        )
+        data = unwrap(resp)
+        check_version(data.get("version") if isinstance(data, dict) else None)
+        self._version_checked = True
+
+    async def open(
+        self,
+        *,
+        shell: Optional[str] = None,
+        cols: int = cfg.DEFAULT_COLS,
+        rows: int = cfg.DEFAULT_ROWS,
+        cwd: Optional[str] = None,
+        env: EnvLike = None,
+    ) -> Dict[str, Any]:
+        return await self.send(
+            {
+                "kind": "open",
+                "shell": shell,
+                "program": None,
+                "cols": cols,
+                "rows": rows,
+                "cwd": cwd,
+                "env": env_pairs(env),
+            }
+        )
+
+    async def run(
+        self,
+        program: str,
+        *args: str,
+        cols: int = cfg.DEFAULT_COLS,
+        rows: int = cfg.DEFAULT_ROWS,
+        cwd: Optional[str] = None,
+        env: EnvLike = None,
+    ) -> Dict[str, Any]:
+        return await self.send(
+            {
+                "kind": "open",
+                "shell": None,
+                "program": [program, *args],
+                "cols": cols,
+                "rows": rows,
+                "cwd": cwd,
+                "env": env_pairs(env),
+            }
+        )
+
+    async def close(self) -> None:
+        if not await transport.can_connect(self._session, self._home):
+            return
+        resp = await transport.request(
+            self._session, self._home, self._binary, {"kind": "close"}, autostart=False
+        )
+        unwrap(resp)
+
+    async def type(self, text: str) -> None:
+        await self.send({"kind": "write", "data": text})
+
+    async def write(self, data: str) -> None:
+        await self.send({"kind": "write", "data": data})
+
+    async def submit(self, text: Optional[str] = None) -> None:
+        await self.send({"kind": "submit", "data": text})
+
+    async def press(self, *keys: str) -> None:
+        await self.send({"kind": "press", "keys": list(keys)})
+
+    async def keys(self, combo: str) -> None:
+        await self.send({"kind": "press", "keys": [combo]})
+
+    async def resize(self, cols: int, rows: int) -> None:
+        await self.send({"kind": "resize", "cols": cols, "rows": rows})
+
+    async def signal(self, name: str) -> None:
+        await self.send({"kind": "signal", "name": name})
+
+    async def kill(self) -> None:
+        await self.send({"kind": "signal", "name": "KILL"})
+
+    async def state(self) -> State:
+        return State.from_dict(await self.send({"kind": "state"}))
+
+    async def text(self, *, full: bool = False) -> str:
+        return (await self.send({"kind": "text", "full": full}))["text"]
+
+    async def cells(self, x: int, y: int, w: int = 1, h: int = 1) -> List[Cell]:
+        data = await self.send({"kind": "cells", "x": x, "y": y, "w": w, "h": h})
+        return [Cell(**c) for c in data["cells"]]
+
+    async def get(self, field: str) -> Any:
+        return (await self.send({"kind": "get", "field": field}))["value"]
+
+    async def get_command(self) -> Optional[str]:
+        return await self.get("command")
+
+    async def get_output(self) -> Optional[str]:
+        return await self.get("output")
+
+    async def get_exit_code(self) -> Optional[int]:
+        return await self.get("exit-code")
+
+    async def get_cwd(self) -> Optional[str]:
+        return await self.get("cwd")
+
+    async def get_cursor(self) -> Dict[str, int]:
+        return await self.get("cursor")
+
+    async def get_size(self) -> Dict[str, int]:
+        return await self.get("size")
+
+    async def screenshot(self, path: Optional[str] = None, *, full: bool = False) -> str:
+        data = await self.send({"kind": "screenshot", "full": full, "path": path})
+        return data.get("path") or data.get("text")
+
+    async def wait_text(
+        self,
+        text: str,
+        *,
+        regex: bool = False,
+        full: bool = False,
+        not_: bool = False,
+        timeout: int = 5000,
+    ) -> None:
+        await self.send(
+            {
+                "kind": "wait_text",
+                "text": text,
+                "regex": regex,
+                "full": full,
+                "timeout_ms": timeout,
+                "not": not_,
+            }
+        )
+
+    async def wait_idle(self, *, timeout: int = 5000) -> None:
+        await self.send({"kind": "wait_idle", "timeout_ms": timeout})
+
+    async def wait_command(self, *, timeout: int = 30000) -> None:
+        await self.send({"kind": "wait_command", "timeout_ms": timeout})
+
+    async def wait_exit(self, *, timeout: int = 30000) -> None:
+        await self.send({"kind": "wait_exit", "timeout_ms": timeout})
+
+    async def expect_text(
+        self,
+        text: str,
+        *,
+        regex: bool = False,
+        full: bool = False,
+        strict: bool = True,
+        not_: bool = False,
+        fg: Optional[str] = None,
+        bg: Optional[str] = None,
+        timeout: int = 5000,
+    ) -> None:
+        await self.send(
+            {
+                "kind": "expect_text",
+                "text": text,
+                "regex": regex,
+                "full": full,
+                "strict": strict,
+                "not": not_,
+                "fg": fg,
+                "bg": bg,
+                "timeout_ms": timeout,
+            }
+        )
+
+    async def expect_exit_code(self, code: int) -> None:
+        await self.send({"kind": "expect_exit_code", "code": code})
+
+    async def expect_output(self, text: str, *, regex: bool = False) -> None:
+        await self.send({"kind": "expect_output", "text": text, "regex": regex})
+
+    async def expect_snapshot(
+        self, name: str, *, update: bool = False, include_colors: bool = False
+    ) -> str:
+        return (
+            await self.send(
+                {
+                    "kind": "snapshot",
+                    "name": name,
+                    "update": update,
+                    "include_colors": include_colors,
+                    "cwd": os.getcwd(),
+                }
+            )
+        )["status"]
+
+    async def __aenter__(self) -> "ShellUse":
+        return self
+
+    async def __aexit__(self, *exc: Any) -> None:
+        await self.close()
+
+
+async def sessions(*, home: Optional[str] = None) -> List[str]:
+    h = cfg.resolve_home(home)
+    directory = cfg.home_dir(h)
+    out: List[str] = []
+    if directory.is_dir():
+        for entry in sorted(directory.iterdir()):
+            if entry.suffix == ".pid":
+                name = entry.stem
+                if await transport.can_connect(name, h):
+                    out.append(name)
+    return out
+
+
+async def close_all(*, binary: Optional[str] = None, home: Optional[str] = None) -> None:
+    h = cfg.resolve_home(home)
+    b = cfg.resolve_binary(binary)
+    for name in await sessions(home=h):
+        try:
+            await transport.request(name, h, b, {"kind": "close"}, autostart=False)
+        except Exception:
+            pass
+
+
+async def daemon_status(
+    session: Optional[str] = None,
+    *,
+    binary: Optional[str] = None,
+    home: Optional[str] = None,
+) -> Dict[str, Any]:
+    s = cfg.resolve_session(session)
+    h = cfg.resolve_home(home)
+    b = cfg.resolve_binary(binary)
+    return unwrap(await transport.request(s, h, b, {"kind": "status"}))
+
+
+async def daemon_stop(
+    session: Optional[str] = None,
+    *,
+    binary: Optional[str] = None,
+    home: Optional[str] = None,
+) -> None:
+    s = cfg.resolve_session(session)
+    h = cfg.resolve_home(home)
+    b = cfg.resolve_binary(binary)
+    if not await transport.can_connect(s, h):
+        return
+    unwrap(await transport.request(s, h, b, {"kind": "shutdown"}, autostart=False))
+
+
+async def get_recording(
+    session: Optional[str] = None, *, home: Optional[str] = None
+) -> str:
+    import asyncio
+
+    s = cfg.resolve_session(session)
+    h = cfg.resolve_home(home)
+    path = cfg.recording_path(s, h)
+    loop = asyncio.get_running_loop()
+    try:
+        data = await loop.run_in_executor(None, path.read_bytes)
+    except FileNotFoundError:
+        from .errors import NoSessionError
+
+        raise NoSessionError(f"no recording for session '{s}'")
+    return data.decode("utf-8", errors="replace")

shell_use-0.0.1b2/src/shell_use/errors.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+
+from typing import Optional
+
+
+class ShellUseError(Exception):
+    kind: str = "internal"
+    exit_code: int = 5
+
+    def __init__(self, message: str) -> None:
+        super().__init__(message)
+        self.message = message
+
+
+class ExpectationError(ShellUseError):
+    kind = "assertion"
+    exit_code = 1
+
+
+class UsageError(ShellUseError):
+    kind = "usage"
+    exit_code = 2
+
+
+class NoSessionError(ShellUseError):
+    kind = "no_session"
+    exit_code = 3
+
+
+class DaemonError(ShellUseError):
+    kind = "daemon"
+    exit_code = 4
+
+
+class VersionMismatchError(ShellUseError):
+    kind = "version_mismatch"
+    exit_code = 4
+
+
+class InternalError(ShellUseError):
+    kind = "internal"
+    exit_code = 5
+
+
+_BY_KIND = {
+    "assertion": ExpectationError,
+    "usage": UsageError,
+    "no_session": NoSessionError,
+    "daemon": DaemonError,
+    "internal": InternalError,
+}
+
+
+def make_error(kind: Optional[str], message: str) -> ShellUseError:
+    """Construct the typed error for a daemon ``kind`` string."""
+    return _BY_KIND.get(kind or "", InternalError)(message)

shell_use-0.0.1b2/src/shell_use/types.py

@@ -0,0 +1,48 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Dict, Optional, Union
+
+Color = Union[str, int]
+
+
+@dataclass
+class Cell:
+    x: int
+    y: int
+    char: str
+    fg: Color
+    bg: Color
+    bold: bool
+    italic: bool
+    underline: bool
+    inverse: bool
+
+
+@dataclass
+class State:
+    cols: int
+    rows: int
+    cursor: Dict[str, int]
+    cwd: Optional[str]
+    last_command: Optional[str]
+    last_exit: Optional[int]
+    exited: Optional[int]
+    ready: bool
+    text: str
+    session_shell: Optional[str]
+
+    @classmethod
+    def from_dict(cls, d: Dict[str, Any]) -> "State":
+        return cls(
+            cols=d.get("cols", 0),
+            rows=d.get("rows", 0),
+            cursor=d.get("cursor", {"x": 0, "y": 0}),
+            cwd=d.get("cwd"),
+            last_command=d.get("last_command"),
+            last_exit=d.get("last_exit"),
+            exited=d.get("exited"),
+            ready=d.get("ready", False),
+            text=d.get("text", ""),
+            session_shell=d.get("session_shell"),
+        )

shell_use-0.0.1/.gitignore

@@ -1,4 +0,0 @@
-/target
-*.gif
-*.trace
-.shell-use/

shell_use-0.0.1/LICENSE

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

shell_use-0.0.1/PKG-INFO

@@ -1,25 +0,0 @@
-Metadata-Version: 2.4
-Name: shell-use
-Version: 0.0.1
-Summary: A headless terminal CLI + daemon for driving, asserting on, and recording shells
-Project-URL: Homepage, https://github.com/microsoft/shell-use
-Project-URL: Repository, https://github.com/microsoft/shell-use
-Project-URL: Issues, https://github.com/microsoft/shell-use/issues
-Author: Microsoft Corporation
-License-Expression: MIT
-License-File: LICENSE
-Keywords: cli,pty,shell,terminal,testing,tui
-Classifier: Development Status :: 1 - Planning
-Classifier: Intended Audience :: Developers
-Classifier: Operating System :: OS Independent
-Classifier: Programming Language :: Python :: 3
-Classifier: Topic :: Software Development :: Testing
-Classifier: Topic :: Terminals
-Requires-Python: >=3.8
-Description-Content-Type: text/markdown
-
-# shell-use
-
-`shell-use` is a Rust-powered CLI for controlling, inspecting, testing, and recording shell sessions and terminal apps.
-
-This package reserves the `shell-use` name on PyPI. See the project repository for the actual tool and installation instructions: https://github.com/microsoft/shell-use

shell_use-0.0.1/README.md

@@ -1,5 +0,0 @@
-# shell-use
-
-`shell-use` is a Rust-powered CLI for controlling, inspecting, testing, and recording shell sessions and terminal apps.
-
-This package reserves the `shell-use` name on PyPI. See the project repository for the actual tool and installation instructions: https://github.com/microsoft/shell-use

shell_use-0.0.1/build.log

@@ -1,5 +0,0 @@
-* Creating isolated environment: venv+pip...
-* Installing packages in isolated environment:
-  - hatchling
-* Getting build dependencies for sdist...
-* Building sdist...

shell_use-0.0.1/pyproject.toml

@@ -1,30 +0,0 @@
-[build-system]
-requires = ["hatchling"]
-build-backend = "hatchling.build"
-
-[project]
-name = "shell-use"
-version = "0.0.1"
-description = "A headless terminal CLI + daemon for driving, asserting on, and recording shells"
-readme = "README.md"
-requires-python = ">=3.8"
-license = "MIT"
-license-files = ["LICENSE"]
-authors = [{ name = "Microsoft Corporation" }]
-keywords = ["terminal", "shell", "cli", "tui", "pty", "testing"]
-classifiers = [
-    "Development Status :: 1 - Planning",
-    "Intended Audience :: Developers",
-    "Operating System :: OS Independent",
-    "Programming Language :: Python :: 3",
-    "Topic :: Software Development :: Testing",
-    "Topic :: Terminals",
-]
-
-[project.urls]
-Homepage = "https://github.com/microsoft/shell-use"
-Repository = "https://github.com/microsoft/shell-use"
-Issues = "https://github.com/microsoft/shell-use/issues"
-
-[tool.hatch.build.targets.wheel]
-packages = ["src/shell_use"]

shell_use-0.0.1/src/shell_use/__init__.py

@@ -1 +0,0 @@
-__version__ = "0.0.1"