pocketshell 0.4.46__tar.gz → 0.5.0__tar.gz

{pocketshell-0.4.46 → pocketshell-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: pocketshell
-Version: 0.4.46
+Version: 0.5.0
 Summary: Unified server-side Python utility for the PocketShell Android client.
 Project-URL: Homepage, https://github.com/alexeygrigorev/pocketshell
 Project-URL: Issues, https://github.com/alexeygrigorev/pocketshell/issues

{pocketshell-0.4.46 → pocketshell-0.5.0}/pyproject.toml

@@ -14,7 +14,7 @@ name = "pocketshell"
 # scripts/check-pypi-version.sh enforces the stamped value matches the tag;
 # scripts/check-version-coupling.sh enforces the derivation itself is
 # single-sourced. See tools/pocketshell/README.md ("Version coupling").
-version = "0.4.46"
+version = "0.5.0"
 description = "Unified server-side Python utility for the PocketShell Android client."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -129,6 +129,10 @@ exclude = [
 ]
 
 [tool.uv]
+# CI and local frozen-sync checks use the same installer semantics. Bump this
+# deliberately together with .github/workflows/tests.yml and validate the
+# committed lock before merging.
+required-version = "==0.10.11"
 # Keep the lockfile's reproducibility cutoff project-local. The host may have
 # a rolling global `exclude-newer` policy that predates deliberately pinned
 # releases (quse 0.0.15 and tmuxctl 0.3.5); this exact value is also the

{pocketshell-0.4.46 → pocketshell-0.5.0}/src/pocketshell/agent_log.py

@@ -539,6 +539,19 @@ def _grok_messages_from_row(row: dict[str, Any]) -> List[HandoffMessage]:
     return []
 
 
+def _handoff_messages_from_row(engine: str, row: dict[str, Any]) -> List[HandoffMessage]:
+    """Dispatch one parsed JSONL row to its per-engine message extractor."""
+    if engine == "claude":
+        return _claude_messages_from_row(row)
+    if engine == "codex":
+        return _codex_messages_from_row(row)
+    if engine == "opencode":
+        return _opencode_messages_from_row(row)
+    if engine == "grok":
+        return _grok_messages_from_row(row)
+    return []
+
+
 def _handoff_messages_from_lines(engine: str, lines: Iterable[str]) -> List[HandoffMessage]:
     """Extract user/assistant prose from raw agent JSONL rows."""
     messages: List[HandoffMessage] = []
@@ -546,14 +559,7 @@ def _handoff_messages_from_lines(engine: str, lines: Iterable[str]) -> List[Hand
         row = _parse_json_line(line)
         if row is None:
             continue
-        if engine == "claude":
-            messages.extend(_claude_messages_from_row(row))
-        elif engine == "codex":
-            messages.extend(_codex_messages_from_row(row))
-        elif engine == "opencode":
-            messages.extend(_opencode_messages_from_row(row))
-        elif engine == "grok":
-            messages.extend(_grok_messages_from_row(row))
+        messages.extend(_handoff_messages_from_row(engine, row))
     return messages
 
 

{pocketshell-0.4.46 → pocketshell-0.5.0}/src/pocketshell/cards.py

@@ -58,6 +58,12 @@ from __future__ import annotations
 import os
 import re
 import sys
+import base64
+import errno
+import fcntl
+import logging
+import tempfile
+from contextlib import contextmanager
 from dataclasses import dataclass
 from datetime import datetime, timezone
 from pathlib import Path
@@ -67,6 +73,10 @@ import click
 
 # Permissions for the per-session card file (owner-only, matches tree.py).
 NEW_FILE_MODE = 0o600
+_LOGGER = logging.getLogger(__name__)
+_UNSUPPORTED_SYNC_ERRNOS = {errno.EINVAL, errno.ENOTSUP}
+if hasattr(errno, "EOPNOTSUPP"):
+    _UNSUPPORTED_SYNC_ERRNOS.add(errno.EOPNOTSUPP)
 
 # Default checklist card id used when ``--id`` is omitted: a session has exactly
 # one "default" checklist unless the agent names them, which keeps the common
@@ -107,7 +117,7 @@ class CardPaths:
     cards_dir: Path
 
     def session_file(self, session: str) -> Path:
-        return self.cards_dir / f"{_sanitise_session(session)}.yaml"
+        return self.cards_dir / f"{_encode_session(session)}.yaml"
 
 
 # Env override for the cards root, so tests (and a non-default deployment) can
@@ -136,16 +146,10 @@ def resolve_paths(
     return CardPaths(cards_dir=base_home / ".pocketshell" / "cards")
 
 
-def _sanitise_session(session: str) -> str:
-    """Sanitise a tmux session name into a safe single-path-segment filename.
-
-    tmux session names cannot contain whitespace but can contain ``/``, ``.``
-    etc.; replace anything outside ``[A-Za-z0-9._-]`` so the name maps to one
-    flat file (no traversal, no nested dirs).
-    """
-    safe = re.sub(r"[^A-Za-z0-9._-]+", "_", session.strip())
-    safe = safe.strip(".") or "session"
-    return safe
+def _encode_session(session: str) -> str:
+    """Reversibly encode a tmux session as one safe path segment."""
+    encoded = base64.urlsafe_b64encode(session.encode("utf-8")).decode("ascii")
+    return "s-" + encoded.rstrip("=")
 
 
 def _ensure_dir(path: Path) -> None:
@@ -156,25 +160,90 @@ def _ensure_dir(path: Path) -> None:
         pass
 
 
+def _durability_barrier(fd: int, *, path: Path, kind: str) -> bool:
+    """Fsync one file or directory, tolerating only unsupported barriers."""
+    while True:
+        try:
+            os.fsync(fd)
+            return True
+        except OSError as error:
+            if error.errno == errno.EINTR:
+                continue
+            if error.errno in _UNSUPPORTED_SYNC_ERRNOS:
+                _LOGGER.warning(
+                    "durability barrier unavailable for %s %s: %s; "
+                    "continuing with atomic publication",
+                    kind,
+                    path,
+                    error,
+                )
+                return False
+            raise
+
+
+def _fsync_directory(path: Path) -> bool:
+    """Fsync a directory after rename when the filesystem supports it."""
+    flags = os.O_RDONLY | getattr(os, "O_DIRECTORY", 0)
+    try:
+        fd = os.open(str(path), flags)
+    except OSError as error:
+        if error.errno in _UNSUPPORTED_SYNC_ERRNOS:
+            _LOGGER.warning(
+                "durability barrier unavailable for directory %s: %s; "
+                "continuing with atomic publication",
+                path,
+                error,
+            )
+            return False
+        raise
+    try:
+        return _durability_barrier(fd, path=path, kind="directory")
+    finally:
+        os.close(fd)
+
+
 def _write_private(path: Path, text: str) -> None:
-    """Write ``text`` to ``path`` atomically with mode 0600 (copied from tree.py)."""
+    """Publish ``text`` atomically with file and directory durability barriers."""
     _ensure_dir(path.parent)
-    tmp = path.with_name(path.name + ".tmp")
-    fd = os.open(str(tmp), os.O_WRONLY | os.O_CREAT | os.O_TRUNC, NEW_FILE_MODE)
+    fd, tmp_name = tempfile.mkstemp(prefix=f".{path.name}.", dir=path.parent)
+    tmp = Path(tmp_name)
+    open_fd = fd
     try:
-        with os.fdopen(fd, "w", encoding="utf-8") as handle:
-            handle.write(text)
+        with os.fdopen(fd, "wb") as handle:
+            open_fd = -1
+            handle.write(text.encode("utf-8"))
+            handle.flush()
+            os.chmod(tmp, NEW_FILE_MODE)
+            _durability_barrier(handle.fileno(), path=tmp, kind="file")
+        os.replace(tmp, path)
+        _fsync_directory(path.parent)
     except BaseException:
+        if open_fd >= 0:
+            try:
+                os.close(open_fd)
+            except OSError:
+                pass
         try:
-            os.unlink(tmp)
+            tmp.unlink()
         except FileNotFoundError:
             pass
+        except OSError:
+            pass
         raise
-    os.replace(tmp, path)
-    try:
-        os.chmod(path, NEW_FILE_MODE)
-    except FileNotFoundError:
-        pass
+
+
+@contextmanager
+def _session_lock(path: Path):
+    """Hold the cross-process advisory lock for one session document."""
+    _ensure_dir(path.parent)
+    lock_path = path.with_suffix(path.suffix + ".lock")
+    fd = os.open(str(lock_path), os.O_RDWR | os.O_CREAT, NEW_FILE_MODE)
+    with os.fdopen(fd, "a+") as lock:
+        fcntl.flock(lock, fcntl.LOCK_EX)
+        try:
+            yield
+        finally:
+            fcntl.flock(lock, fcntl.LOCK_UN)
 
 
 # ---------------------------------------------------------------------------
@@ -427,9 +496,7 @@ def _import_yaml() -> Any:
     return yaml
 
 
-def read_cards(session: str, *, paths: CardPaths) -> list[dict[str, Any]]:
-    """Return the session's list of cards (empty when none / unreadable)."""
-    path = paths.session_file(session)
+def _read_cards_file(path: Path, session: str) -> list[dict[str, Any]]:
     try:
         raw = path.read_text(encoding="utf-8")
     except (FileNotFoundError, IsADirectoryError, PermissionError):
@@ -443,14 +510,28 @@ def read_cards(session: str, *, paths: CardPaths) -> list[dict[str, Any]]:
         return []
     if not isinstance(doc, Mapping):
         return []
+    if doc.get("session") != session:
+        return []
     cards = doc.get("cards")
     if not isinstance(cards, list):
         return []
     return [dict(c) for c in cards if isinstance(c, Mapping)]
 
 
+def read_cards(session: str, *, paths: CardPaths) -> list[dict[str, Any]]:
+    """Return the session's list of cards (empty when none / unreadable)."""
+    return _read_cards_file(paths.session_file(session), session)
+
+
 def write_cards(session: str, cards: list[dict[str, Any]], *, paths: CardPaths) -> Path:
     """Atomically persist the session's card list as YAML. Returns the path."""
+    path = paths.session_file(session)
+    with _session_lock(path):
+        _write_cards_file(path, session, cards)
+    return path
+
+
+def _write_cards_file(path: Path, session: str, cards: list[dict[str, Any]]) -> None:
     yaml = _import_yaml()
     doc = {
         "schema": 1,
@@ -459,9 +540,22 @@ def write_cards(session: str, cards: list[dict[str, Any]], *, paths: CardPaths)
         "cards": cards,
     }
     text = yaml.safe_dump(doc, sort_keys=False, default_flow_style=False)
-    path = paths.session_file(session)
     _write_private(path, text)
-    return path
+
+
+def _mutate_cards(
+    session: str,
+    *,
+    paths: CardPaths,
+    mutation: Callable[[list[dict[str, Any]]], Any],
+) -> tuple[Path, Any]:
+    """Apply one read-modify-write transaction under the session lock."""
+    path = paths.session_file(session)
+    with _session_lock(path):
+        cards = _read_cards_file(path, session)
+        result = mutation(cards)
+        _write_cards_file(path, session, cards)
+    return path, result
 
 
 # ---------------------------------------------------------------------------
@@ -513,11 +607,13 @@ def upsert_card(session: str, card: dict[str, Any], *, paths: CardPaths) -> Path
     Replace preserves nothing of the old card — a re-push of a checklist by the
     agent is a full replace (hard-cut semantics; the new list is authoritative).
     """
-    cards = read_cards(session, paths=paths)
-    card_id = card["id"]
-    cards = [c for c in cards if c.get("id") != card_id]
-    cards.append(card)
-    return write_cards(session, cards, paths=paths)
+    def mutate(cards: list[dict[str, Any]]) -> None:
+        card_id = card["id"]
+        cards[:] = [c for c in cards if c.get("id") != card_id]
+        cards.append(card)
+
+    path, _ = _mutate_cards(session, paths=paths, mutation=mutate)
+    return path
 
 
 def apply_interaction(
@@ -532,23 +628,20 @@ def apply_interaction(
     Raises :class:`ValueError` when the card id is not found in the session, or
     when the type's :meth:`apply_interaction` rejects the interaction.
     """
-    cards = read_cards(session, paths=paths)
-    target: Optional[dict[str, Any]] = None
-    for card in cards:
-        if card.get("id") == card_id:
-            target = card
-            break
-    if target is None:
-        raise ValueError(f"no card with id {card_id!r} in session {session!r}")
-    handler = get_card_type(target.get("type", ""))
-    if handler is None:
-        raise ValueError(f"card {card_id!r} has unknown type {target.get('type')!r}")
-    body = target.get("body", {}) if isinstance(target.get("body"), Mapping) else {}
-    state = target.get("state", {}) if isinstance(target.get("state"), Mapping) else {}
-    new_state = handler.apply_interaction(dict(body), dict(state), interaction)
-    target["state"] = new_state
-    target["updated_at"] = _now_iso()
-    write_cards(session, cards, paths=paths)
+    def mutate(cards: list[dict[str, Any]]) -> dict[str, Any]:
+        target = next((card for card in cards if card.get("id") == card_id), None)
+        if target is None:
+            raise ValueError(f"no card with id {card_id!r} in session {session!r}")
+        handler = get_card_type(target.get("type", ""))
+        if handler is None:
+            raise ValueError(f"card {card_id!r} has unknown type {target.get('type')!r}")
+        body = target.get("body", {}) if isinstance(target.get("body"), Mapping) else {}
+        state = target.get("state", {}) if isinstance(target.get("state"), Mapping) else {}
+        target["state"] = handler.apply_interaction(dict(body), dict(state), interaction)
+        target["updated_at"] = _now_iso()
+        return target
+
+    _, target = _mutate_cards(session, paths=paths, mutation=mutate)
     return target
 
 

pocketshell-0.5.0/src/pocketshell/config.py

@@ -0,0 +1,163 @@
+"""Host-level PocketShell CLI configuration (``~/.config/pocketshell/config.toml``).
+
+Today this file carries exactly one section — ``[backends]`` — the per-host
+policy that decides which session backend a *new* session is created on:
+
+.. code-block:: toml
+
+    [backends]
+    agent = "tmux"      # sessions created with --engine
+    shell = "tmux"      # plain shell sessions
+
+Why a pocketshell-owned config file rather than a flag or a backend-side
+setting: routing is deployment policy that spans BOTH backends, and neither
+backend can answer "not me" (see the simplification plan, §"Backend routing
+policy"). The phone never sends a backend; the host decides.
+
+Defaults are ``tmux`` for both keys. Flipping ``agent = "aplexer"`` is a
+deliberate host config change the maintainer makes — never a code change and
+never an automatic upgrade.
+
+Parsing rules (deliberate, see ``load_config``):
+
+* missing file / empty file -> defaults;
+* malformed TOML, a non-table ``[backends]``, or an unknown backend value ->
+  :class:`ConfigError`, i.e. **fail loud**. Silently falling back to the
+  defaults would route agent sessions to tmux while the host owner believes
+  aplexer is switched on — a wrong-path failure that shows up as "the feature
+  just doesn't work", which is exactly the class of silent misroute this
+  project rejects. A typo in a two-line file is cheap to fix once it is
+  reported; a silent misroute is not.
+
+``tomllib`` is used unconditionally: this package's ``requires-python`` is
+``>=3.11``, where ``tomllib`` is stdlib, so there is no ``tomli`` fallback to
+maintain (D22: no compatibility shims).
+"""
+
+from __future__ import annotations
+
+import os
+import tomllib
+from pathlib import Path
+from typing import Any, Mapping, Optional
+
+#: Session backends this CLI knows how to create on.
+BACKEND_TMUX = "tmux"
+BACKEND_APLEXER = "aplexer"
+BACKENDS = (BACKEND_TMUX, BACKEND_APLEXER)
+
+#: Backend used when the config file says nothing.
+DEFAULT_BACKEND = BACKEND_TMUX
+
+#: ``[backends]`` keys: ``agent`` covers a session launched with an engine,
+#: ``shell`` a plain shell session.
+BACKEND_KEY_AGENT = "agent"
+BACKEND_KEY_SHELL = "shell"
+BACKEND_KEYS = (BACKEND_KEY_AGENT, BACKEND_KEY_SHELL)
+
+DEFAULT_BACKENDS: dict[str, str] = {
+    BACKEND_KEY_AGENT: DEFAULT_BACKEND,
+    BACKEND_KEY_SHELL: DEFAULT_BACKEND,
+}
+
+
+class ConfigError(RuntimeError):
+    """``config.toml`` exists but cannot be trusted (malformed / bad value)."""
+
+
+def _env_source(env: Optional[Mapping[str, str]] = None) -> Mapping[str, str]:
+    return env if env is not None else os.environ
+
+
+def _home_dir(env: Optional[Mapping[str, str]] = None) -> Path:
+    """Resolve ``$HOME`` (honouring an injected env for tests)."""
+    home = _env_source(env).get("HOME")
+    if home:
+        return Path(home)
+    return Path(os.path.expanduser("~"))
+
+
+def config_path(env: Optional[Mapping[str, str]] = None) -> Path:
+    """``$XDG_CONFIG_HOME``/``~/.config`` + ``pocketshell/config.toml``.
+
+    Same resolution order as ``profiles.py``'s ``profiles.yaml`` so a host
+    keeps all PocketShell config in one directory.
+    """
+    xdg = _env_source(env).get("XDG_CONFIG_HOME")
+    base = Path(xdg) if xdg else _home_dir(env) / ".config"
+    return base / "pocketshell" / "config.toml"
+
+
+def default_config() -> dict[str, Any]:
+    """A fresh copy of the fully-defaulted config document."""
+    return {"backends": dict(DEFAULT_BACKENDS)}
+
+
+def _normalize_backends(raw: Any, *, path: Path) -> dict[str, str]:
+    """Validate the ``[backends]`` table and merge it over the defaults."""
+    backends = dict(DEFAULT_BACKENDS)
+    if raw is None:
+        return backends
+    if not isinstance(raw, Mapping):
+        raise ConfigError(
+            f"{path}: [backends] must be a table, got {type(raw).__name__}"
+        )
+    for key, value in raw.items():
+        if key not in BACKEND_KEYS:
+            raise ConfigError(
+                f"{path}: unknown key [backends].{key} "
+                f"(known keys: {', '.join(BACKEND_KEYS)})"
+            )
+        if not isinstance(value, str) or value.strip() not in BACKENDS:
+            raise ConfigError(
+                f"{path}: [backends].{key} must be one of "
+                f"{', '.join(BACKENDS)}, got {value!r}"
+            )
+        backends[key] = value.strip()
+    return backends
+
+
+def load_config(env: Optional[Mapping[str, str]] = None) -> dict[str, Any]:
+    """Read ``~/.config/pocketshell/config.toml``.
+
+    Returns the parsed document with a fully-populated ``backends`` table
+    (every key present, defaults filled in) so callers never have to probe for
+    key presence. Any other top-level table the file happens to carry is
+    passed through untouched — this loader owns ``[backends]`` only.
+
+    A missing file returns the defaults. A file that exists but is malformed
+    (bad TOML, non-table ``[backends]``, unknown key, unknown backend value,
+    unreadable) raises :class:`ConfigError` — see the module docstring for why
+    this fails loud instead of degrading to defaults.
+    """
+    path = config_path(env)
+    if not path.is_file():
+        return default_config()
+    try:
+        raw_bytes = path.read_bytes()
+    except OSError as exc:
+        raise ConfigError(f"{path}: cannot be read: {exc}") from exc
+    try:
+        document = tomllib.loads(raw_bytes.decode("utf-8"))
+    except (UnicodeDecodeError, tomllib.TOMLDecodeError) as exc:
+        raise ConfigError(f"{path}: is not valid TOML: {exc}") from exc
+    if not isinstance(document, dict):  # pragma: no cover - tomllib invariant
+        raise ConfigError(f"{path}: top level must be a table")
+    normalized = dict(document)
+    normalized["backends"] = _normalize_backends(document.get("backends"), path=path)
+    return normalized
+
+
+def backend_for(config: Mapping[str, Any], key: str) -> str:
+    """Read one ``[backends]`` key out of a (possibly partial) config dict.
+
+    Tolerant on purpose: :func:`load_config` is the strict validator, and this
+    accessor is also handed hand-built dicts (tests, callers that skipped the
+    loader). Anything missing or not a usable string resolves to
+    :data:`DEFAULT_BACKEND`.
+    """
+    backends = config.get("backends") if isinstance(config, Mapping) else None
+    value = backends.get(key) if isinstance(backends, Mapping) else None
+    if isinstance(value, str) and value.strip():
+        return value.strip()
+    return DEFAULT_BACKEND