muxplex-client 0.19.0__tar.gz

muxplex_client-0.19.0/.gitignore

@@ -0,0 +1,30 @@
+# Python bytecode
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+
+# Virtual environment
+.venv/
+venv/
+env/
+
+# Distribution / packaging
+dist/
+build/
+*.egg-info/
+
+# Test/coverage artifacts
+.coverage
+.pytest_cache/
+htmlcov/
+
+# OS artifacts
+.DS_Store
+Thumbs.db
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo

muxplex_client-0.19.0/PKG-INFO

@@ -0,0 +1,128 @@
+Metadata-Version: 2.4
+Name: muxplex-client
+Version: 0.19.0
+Summary: Typed sync/async HTTP client for the muxplex API
+Project-URL: Repository, https://github.com/bkrabach/muxplex
+Project-URL: Issues, https://github.com/bkrabach/muxplex/issues
+Author-email: Brian Krabach <brian@krabach.com>
+License: MIT
+Keywords: api,client,http,muxplex,tmux
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# muxplex-client
+
+Typed sync/async HTTP client for the [muxplex](https://github.com/bkrabach/muxplex)
+tmux-session-dashboard API.
+
+Ships as its own PyPI distribution (import name `muxplex_client`) so a
+consumer that only needs to make ~12 HTTP calls -- a Stream Deck sidecar, an
+Amplifier tool module -- never has to install the server's dependencies
+(fastapi, uvicorn, python-pam, ...) or its `muxplex` server console script.
+See [`../muxplex-client-design.md`](../muxplex-client-design.md) for the full
+design rationale.
+
+## Install
+
+```bash
+pip install muxplex-client
+```
+
+Runtime dependency: `httpx>=0.27.0`. Nothing else -- no `muxplex` server
+dependency, no console script installed.
+
+## Usage
+
+Synchronous:
+
+```python
+from muxplex_client import MuxplexClient
+
+with MuxplexClient("https://your-server:8088", "federation-key") as client:
+    for session in client.sessions():
+        if session.bell.needs_attention:
+            print(f"{session.name} needs attention")
+```
+
+Asynchronous (Amplifier tool modules, or any asyncio caller):
+
+```python
+from muxplex_client import AsyncMuxplexClient
+
+async with AsyncMuxplexClient("https://your-server:8088", "federation-key") as client:
+    result = await client.run_shell_command("my-session", "pytest -q")
+    print(result.exit_code, result.elapsed)
+```
+
+A localhost caller needs no credential -- `federation_key=None` is the
+default and is fine when running on the same host as the server.
+
+## What's in here vs. what isn't
+
+See `muxplex-client-design.md` §3 for the full included/excluded endpoint
+table and rationale. Notably excluded: `PATCH /api/settings` (highest
+blast-radius operation in the API; a v2 concern requiring CAS + 409 retry +
+backstop discrimination), all federation endpoints (server-to-server
+protocol, no client consumer), and `/api/internal/setup-hooks` (internal,
+self-healing as of server v0.18.0).
+
+## Version alignment
+
+`muxplex_client.__version__` is cut in lockstep with the muxplex server
+version -- one `vX.Y.Z` tag publishes both wheels. This is provenance
+("cut against server X"), not a runtime requirement: the client declares no
+dependency on the `muxplex` package and enforces no version at runtime.
+`MIN_SERVER_VERSION` backs an opt-in `check_server()` helper the caller may
+call; it is never invoked automatically.
+
+The load-bearing correctness mechanism is
+`muxplex/tests/test_client_contract.py`, living in the **server's** own test
+suite: it drives this client over `httpx.ASGITransport` against the real
+FastAPI app and asserts every field the client parses actually exists on the
+real response, that mirrored constants (`KNOWN_KEYS`, `MAX_CAPTURE_LINES`,
+`DEFAULT_CAPTURE_LINES`) equal their server originals, and that
+`Bell.needs_attention` agrees with the server's own predicate across a truth
+table.
+
+## The shell-command sentinel
+
+`run_shell_command()` (and the lower-level `muxplex_client.sentinel` module)
+implements the completion-detection convention from `AGENT_GUIDE.md` §6.2/§6.4:
+wrap a command with `; rc=$?; ... ; echo "MUXPLEX_DONE_<token>_EXIT_$rc"` and
+poll the pane for the marker.
+
+**This assumes the target pane is an idle POSIX shell prompt.** It is *not* a
+general HTTP contract -- it fails (types a garbage line into whatever is
+actually running, then hangs until timeout) against vim, a REPL, `less`, a
+TUI, an ssh session, or a non-POSIX shell without a matching `exit_expr`.
+
+The one correctness rule worth calling out explicitly: matching must be
+**digit-anchored** (`MUXPLEX_DONE_<token>_EXIT_(\d+)`), never a bare-token
+substring check. tmux echoes the literal, unexpanded `...EXIT_$?` into the
+pane the instant you send the line -- before the shell has even run it -- so
+a bare-token match reports "done" with a bogus exit code immediately. See
+`muxplex_client/sentinel.py`'s docstring and `tests/test_sentinel.py`'s
+digit-anchor regression test.
+
+## Development
+
+```bash
+uv sync --extra dev   # from this directory, or from the repo root via the
+                       # [tool.uv.workspace] declaration
+uv run pytest
+```
+
+`tests/` is pure -- no network, no server import, and passes with `muxplex`
+not installed at all.

muxplex_client-0.19.0/README.md

@@ -0,0 +1,104 @@
+# muxplex-client
+
+Typed sync/async HTTP client for the [muxplex](https://github.com/bkrabach/muxplex)
+tmux-session-dashboard API.
+
+Ships as its own PyPI distribution (import name `muxplex_client`) so a
+consumer that only needs to make ~12 HTTP calls -- a Stream Deck sidecar, an
+Amplifier tool module -- never has to install the server's dependencies
+(fastapi, uvicorn, python-pam, ...) or its `muxplex` server console script.
+See [`../muxplex-client-design.md`](../muxplex-client-design.md) for the full
+design rationale.
+
+## Install
+
+```bash
+pip install muxplex-client
+```
+
+Runtime dependency: `httpx>=0.27.0`. Nothing else -- no `muxplex` server
+dependency, no console script installed.
+
+## Usage
+
+Synchronous:
+
+```python
+from muxplex_client import MuxplexClient
+
+with MuxplexClient("https://your-server:8088", "federation-key") as client:
+    for session in client.sessions():
+        if session.bell.needs_attention:
+            print(f"{session.name} needs attention")
+```
+
+Asynchronous (Amplifier tool modules, or any asyncio caller):
+
+```python
+from muxplex_client import AsyncMuxplexClient
+
+async with AsyncMuxplexClient("https://your-server:8088", "federation-key") as client:
+    result = await client.run_shell_command("my-session", "pytest -q")
+    print(result.exit_code, result.elapsed)
+```
+
+A localhost caller needs no credential -- `federation_key=None` is the
+default and is fine when running on the same host as the server.
+
+## What's in here vs. what isn't
+
+See `muxplex-client-design.md` §3 for the full included/excluded endpoint
+table and rationale. Notably excluded: `PATCH /api/settings` (highest
+blast-radius operation in the API; a v2 concern requiring CAS + 409 retry +
+backstop discrimination), all federation endpoints (server-to-server
+protocol, no client consumer), and `/api/internal/setup-hooks` (internal,
+self-healing as of server v0.18.0).
+
+## Version alignment
+
+`muxplex_client.__version__` is cut in lockstep with the muxplex server
+version -- one `vX.Y.Z` tag publishes both wheels. This is provenance
+("cut against server X"), not a runtime requirement: the client declares no
+dependency on the `muxplex` package and enforces no version at runtime.
+`MIN_SERVER_VERSION` backs an opt-in `check_server()` helper the caller may
+call; it is never invoked automatically.
+
+The load-bearing correctness mechanism is
+`muxplex/tests/test_client_contract.py`, living in the **server's** own test
+suite: it drives this client over `httpx.ASGITransport` against the real
+FastAPI app and asserts every field the client parses actually exists on the
+real response, that mirrored constants (`KNOWN_KEYS`, `MAX_CAPTURE_LINES`,
+`DEFAULT_CAPTURE_LINES`) equal their server originals, and that
+`Bell.needs_attention` agrees with the server's own predicate across a truth
+table.
+
+## The shell-command sentinel
+
+`run_shell_command()` (and the lower-level `muxplex_client.sentinel` module)
+implements the completion-detection convention from `AGENT_GUIDE.md` §6.2/§6.4:
+wrap a command with `; rc=$?; ... ; echo "MUXPLEX_DONE_<token>_EXIT_$rc"` and
+poll the pane for the marker.
+
+**This assumes the target pane is an idle POSIX shell prompt.** It is *not* a
+general HTTP contract -- it fails (types a garbage line into whatever is
+actually running, then hangs until timeout) against vim, a REPL, `less`, a
+TUI, an ssh session, or a non-POSIX shell without a matching `exit_expr`.
+
+The one correctness rule worth calling out explicitly: matching must be
+**digit-anchored** (`MUXPLEX_DONE_<token>_EXIT_(\d+)`), never a bare-token
+substring check. tmux echoes the literal, unexpanded `...EXIT_$?` into the
+pane the instant you send the line -- before the shell has even run it -- so
+a bare-token match reports "done" with a bogus exit code immediately. See
+`muxplex_client/sentinel.py`'s docstring and `tests/test_sentinel.py`'s
+digit-anchor regression test.
+
+## Development
+
+```bash
+uv sync --extra dev   # from this directory, or from the repo root via the
+                       # [tool.uv.workspace] declaration
+uv run pytest
+```
+
+`tests/` is pure -- no network, no server import, and passes with `muxplex`
+not installed at all.

muxplex_client-0.19.0/muxplex_client/__init__.py

@@ -0,0 +1,95 @@
+"""muxplex_client -- typed sync/async HTTP client for the muxplex API.
+
+Basic usage:
+
+    >>> from muxplex_client import MuxplexClient
+    >>> with MuxplexClient("https://your-server:8088", "federation-key") as client:
+    ...     sessions = client.sessions()
+
+Async usage:
+
+    >>> from muxplex_client import AsyncMuxplexClient
+    >>> async with AsyncMuxplexClient("https://your-server:8088", "federation-key") as client:
+    ...     sessions = await client.sessions()
+
+See ../README.md and ../../muxplex-client-design.md for the full design
+rationale (why this is a second distribution, version-alignment policy, the
+sentinel's digit-anchor rule, and what was deliberately excluded).
+"""
+
+from __future__ import annotations
+
+import importlib.metadata
+
+from .async_client import AsyncMuxplexClient
+from .constants import (
+    DEFAULT_CAPTURE_LINES,
+    KNOWN_KEYS,
+    MAX_CAPTURE_LINES,
+    MAX_KEYS,
+    MIN_SERVER_VERSION,
+)
+from .errors import (
+    ApiError,
+    AuthError,
+    CommandTimeout,
+    InputForbidden,
+    MuxplexError,
+    SessionNotFound,
+    UnreachableError,
+)
+from .models import (
+    Bell,
+    CommandResult,
+    ConnectResult,
+    InputResult,
+    InstanceInfo,
+    ServerState,
+    Session,
+    SessionSnapshot,
+    Settings,
+    View,
+    ViewResult,
+    ViewSession,
+)
+from .sentinel import Sentinel, make_sentinel
+from .sync_client import MuxplexClient
+
+try:
+    __version__ = importlib.metadata.version("muxplex-client")
+except importlib.metadata.PackageNotFoundError:
+    # Editable/workspace checkout with no build metadata yet (e.g. running
+    # straight from a source tree before an initial `uv sync`).
+    __version__ = "0.0.0.dev0"
+
+__all__ = [
+    "__version__",
+    "ApiError",
+    "AsyncMuxplexClient",
+    "AuthError",
+    "Bell",
+    "CommandResult",
+    "CommandTimeout",
+    "ConnectResult",
+    "DEFAULT_CAPTURE_LINES",
+    "InputForbidden",
+    "InputResult",
+    "InstanceInfo",
+    "KNOWN_KEYS",
+    "MAX_CAPTURE_LINES",
+    "MAX_KEYS",
+    "MIN_SERVER_VERSION",
+    "MuxplexClient",
+    "MuxplexError",
+    "Sentinel",
+    "ServerState",
+    "Session",
+    "SessionNotFound",
+    "SessionSnapshot",
+    "Settings",
+    "UnreachableError",
+    "View",
+    "ViewResult",
+    "ViewSession",
+    "make_sentinel",
+]

muxplex_client-0.19.0/muxplex_client/_protocol.py

@@ -0,0 +1,215 @@
+"""Pure protocol logic: response parsing and error mapping.
+
+No I/O, no httpx import -- tested once in `tests/test_protocol.py` with no
+network. `sync_client.py` and `async_client.py` are each a thin, ~120-line
+await-shaped (or not) shell that calls into this module; duplication is
+confined to that shell, where it is honest and cheap (this is what httpx
+itself does for its own sync/async split).
+
+`.get()`-based parsing throughout, deliberately: AGENTS.md requires clients
+to tolerate unknown fields and the server to tolerate their absence. Missing
+keys fall back to a sane default rather than raising KeyError.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Mapping, Sequence
+
+from .constants import DEFAULT_CAPTURE_LINES
+from .errors import ApiError, AuthError, InputForbidden, MuxplexError, SessionNotFound
+from .models import (
+    Bell,
+    ConnectResult,
+    InputResult,
+    InstanceInfo,
+    ServerState,
+    Session,
+    SessionSnapshot,
+    Settings,
+    View,
+    ViewResult,
+    ViewSession,
+)
+
+__all__ = [
+    "map_status_error",
+    "parse_bell",
+    "parse_session",
+    "parse_sessions",
+    "parse_session_snapshot",
+    "parse_view_session",
+    "parse_view_result",
+    "parse_server_state",
+    "parse_view",
+    "parse_settings",
+    "parse_instance_info",
+    "parse_connect_result",
+    "parse_input_result",
+    "version_tuple",
+]
+
+
+# ---------------------------------------------------------------------------
+# Response parsing
+# ---------------------------------------------------------------------------
+
+
+def parse_bell(raw: Mapping[str, Any]) -> Bell:
+    return Bell(
+        last_fired_at=raw.get("last_fired_at"),
+        seen_at=raw.get("seen_at"),
+        unseen_count=int(raw.get("unseen_count", 0)),
+    )
+
+
+def parse_session(raw: Mapping[str, Any]) -> Session:
+    return Session(
+        name=raw["name"],
+        snapshot=raw.get("snapshot", ""),
+        bell=parse_bell(raw.get("bell") or {}),
+        last_activity_at=raw.get("last_activity_at"),
+    )
+
+
+def parse_sessions(raw: Sequence[Mapping[str, Any]]) -> list[Session]:
+    return [parse_session(item) for item in raw]
+
+
+def parse_session_snapshot(raw: Mapping[str, Any]) -> SessionSnapshot:
+    return SessionSnapshot(
+        name=raw["name"],
+        snapshot=raw.get("snapshot", ""),
+        lines=int(raw.get("lines", DEFAULT_CAPTURE_LINES)),
+        bell=parse_bell(raw.get("bell") or {}),
+        last_activity_at=raw.get("last_activity_at"),
+    )
+
+
+def parse_view_session(raw: Mapping[str, Any]) -> ViewSession:
+    return ViewSession(
+        name=raw["name"],
+        active=bool(raw.get("active", False)),
+        needs_attention=bool(raw.get("needs_attention", False)),
+        bell=parse_bell(raw.get("bell") or {}),
+        last_activity_at=raw.get("last_activity_at"),
+    )
+
+
+def parse_view_result(raw: Mapping[str, Any]) -> ViewResult:
+    return ViewResult(
+        view=raw.get("view", "all"),
+        views=tuple(raw.get("views") or ()),
+        sort=raw.get("sort", "server"),
+        sessions=tuple(parse_view_session(s) for s in (raw.get("sessions") or ())),
+    )
+
+
+def parse_server_state(raw: Mapping[str, Any]) -> ServerState:
+    return ServerState(
+        active_session=raw.get("active_session"),
+        active_view=raw.get("active_view") or "all",
+        settings_updated_at=raw.get("settings_updated_at"),
+        raw=raw,
+    )
+
+
+def parse_view(raw: Mapping[str, Any]) -> View:
+    return View(
+        name=raw.get("name", ""),
+        sessions=frozenset(raw.get("sessions") or ()),
+    )
+
+
+def parse_settings(raw: Mapping[str, Any]) -> Settings:
+    return Settings(
+        views=tuple(parse_view(v) for v in (raw.get("views") or ())),
+        hidden_sessions=frozenset(raw.get("hidden_sessions") or ()),
+        sort_order=raw.get("sort_order", "manual"),
+        raw=raw,
+    )
+
+
+def parse_instance_info(raw: Mapping[str, Any]) -> InstanceInfo:
+    return InstanceInfo(
+        name=raw.get("name", ""),
+        device_id=raw.get("device_id", ""),
+        version=raw.get("version", ""),
+        federation_enabled=bool(raw.get("federation_enabled", False)),
+        tmux_socket_dir=raw.get("tmux_socket_dir"),
+        bell_hook_armed=raw.get("bell_hook_armed"),
+        raw=raw,
+    )
+
+
+def parse_connect_result(raw: Mapping[str, Any]) -> ConnectResult:
+    return ConnectResult(
+        active_session=raw["active_session"],
+        ttyd_port=int(raw["ttyd_port"]),
+    )
+
+
+def parse_input_result(raw: Mapping[str, Any]) -> InputResult:
+    return InputResult(
+        session=raw["session"],
+        snapshot=raw.get("snapshot", ""),
+    )
+
+
+# ---------------------------------------------------------------------------
+# Error mapping
+# ---------------------------------------------------------------------------
+
+
+def map_status_error(
+    status: int,
+    path: str,
+    detail: str,
+    *,
+    session_name: str | None = None,
+) -> MuxplexError:
+    """Map an HTTP error status + path to the matching MuxplexError subclass.
+
+    Rules (applied in order):
+      - 401 -> AuthError (credential rejected).
+      - 403 from a path ending in "/input" -> InputForbidden (the operator's
+        allowlist fence, NOT a bad credential).
+      - 403 from any other path -> AuthError.
+      - 404 -> SessionNotFound (session_name is whatever the caller was
+        targeting; right after create_session() this can be the read-model
+        poll cache rather than a real failure).
+      - Anything else -> ApiError(status, detail).
+    """
+    if status == 401:
+        return AuthError(detail)
+    if status == 403:
+        if path.endswith("/input"):
+            return InputForbidden(session_name or "", detail)
+        return AuthError(detail)
+    if status == 404:
+        return SessionNotFound(session_name or "", detail)
+    return ApiError(status, detail)
+
+
+# ---------------------------------------------------------------------------
+# Version comparison (backs the opt-in check_server() helper)
+# ---------------------------------------------------------------------------
+
+
+def version_tuple(version: str) -> tuple[int, ...]:
+    """Parse a dotted version string into a comparable tuple of ints.
+
+    Deliberately lenient: non-numeric suffixes (e.g. "1.2.3rc1") are reduced
+    to their leading digits, and an entirely non-numeric segment becomes 0
+    rather than raising -- this is a convenience comparison for an opt-in
+    caller, not a strict semver parser.
+    """
+    parts: list[int] = []
+    for piece in version.split("."):
+        digits = ""
+        for ch in piece:
+            if ch.isdigit():
+                digits += ch
+            else:
+                break
+        parts.append(int(digits) if digits else 0)
+    return tuple(parts)