pocketshell 0.4.17__tar.gz → 0.4.18__tar.gz

{pocketshell-0.4.17 → pocketshell-0.4.18}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pocketshell
-Version: 0.4.17
+Version: 0.4.18
 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.17 → pocketshell-0.4.18}/pyproject.toml

@@ -8,7 +8,7 @@ name = "pocketshell"
 # scripts/check-pypi-version.sh enforces this; .github/workflows/build.yml
 # runs that check before publishing to PyPI. See
 # tools/pocketshell/README.md ("Release flow") for the bump procedure.
-version = "0.4.17"
+version = "0.4.18"
 description = "Unified server-side Python utility for the PocketShell Android client."
 readme = "README.md"
 requires-python = ">=3.11"

pocketshell-0.4.18/src/pocketshell/agent_card_push.py

@@ -0,0 +1,263 @@
+"""Server-side FCM push when an agent posts a typed card (epic #859, Slice D).
+
+This is the card sibling of :mod:`pocketshell.push` (which owns the usage-reset
+FCM path, #690). When a running agent calls ``pocketshell push checklist`` the
+host writes/updates a per-session card (:mod:`pocketshell.cards`); this module
+fires a best-effort FCM **data** push so the phone surfaces a heads-up
+notification that opens the session's card feed.
+
+Why a separate module (not inside :mod:`pocketshell.cards`)
+----------------------------------------------------------
+
+The card store and the FCM device token live in **two different state homes**
+(the #859 research spike's risk #1): cards under ``~/.pocketshell/cards/`` and
+the registered device token under the usage state dir
+(``$XDG_STATE_HOME/pocketshell/usage/push-token.json``). Rather than have
+:mod:`pocketshell.cards` import the token storage directly, the bridge lives
+here: it reads the token via :func:`pocketshell.push.read_token` and sends via
+:class:`pocketshell.push.FcmSender` — the exact same sender/credential the
+usage-reset path uses. Adding a second card type later (``note``) reuses this
+verbatim.
+
+Hard-cut (D22): the app receive path adds a NEW ``type=agent_card`` payload
+sibling to ``usage_reset`` — this module never emits ``usage_reset``.
+
+Fail-soft (matches :func:`pocketshell.push.push_reset_events`): no registered
+token, no service-account credential, or no :mod:`google.auth` installed → the
+trigger no-ops and returns ``None`` WITHOUT raising. ``pocketshell push
+checklist`` must never break because Firebase isn't set up.
+
+De-dup
+------
+
+A successful send records a deterministic **content key** under the cards dir
+(``push-sent.jsonl``) so re-pushing the *same* card (an agent re-runs the same
+``push checklist``) does not re-POST, while an *updated* card (different items /
+title) produces a new key and DOES push. The app's ``PushDedupStore`` is a
+second line of defence on the device; this is the server-side primary guard.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import socket
+from pathlib import Path
+from typing import Any, Optional
+
+from pocketshell import push as push_mod
+from pocketshell.cards import CardPaths
+from pocketshell.usage_capture import _append_history, resolve_paths as resolve_usage_paths
+
+# The app contract: an agent-card push is a `type=agent_card` FCM data message.
+AGENT_CARD_PUSH_TYPE = "agent_card"
+
+# Per-session content-key log so a re-push of an unchanged card never re-POSTs.
+# Lives under the cards dir (NOT the usage dir) — co-located with the cards it
+# de-dups. One small file is plenty: cards are rare and bounded.
+SENT_LOG_FILENAME = "push-sent.jsonl"
+DEFAULT_SENT_LOG_MAX_LINES = 1000
+
+
+def sent_log_file(paths: CardPaths) -> Path:
+    """Return the per-content-key already-pushed log path for ``paths``."""
+    return paths.cards_dir / SENT_LOG_FILENAME
+
+
+def sent_card_keys(paths: CardPaths) -> set[str]:
+    """Return the set of card content keys already successfully pushed."""
+    path = sent_log_file(paths)
+    if not path.exists():
+        return set()
+    keys: set[str] = set()
+    try:
+        text = path.read_text(encoding="utf-8")
+    except OSError:
+        return set()
+    for line in text.splitlines():
+        if not line.strip():
+            continue
+        try:
+            parsed = json.loads(line)
+        except json.JSONDecodeError:
+            continue
+        if isinstance(parsed, dict):
+            key = parsed.get("card_key")
+            if isinstance(key, str) and key:
+                keys.add(key)
+    return keys
+
+
+def _mark_sent(
+    card_key: str,
+    *,
+    paths: CardPaths,
+    sent_log_max_lines: int = DEFAULT_SENT_LOG_MAX_LINES,
+) -> None:
+    """Record ``card_key`` as successfully pushed so it never re-POSTs."""
+    _append_history(
+        sent_log_file(paths),
+        {"card_key": card_key},
+        history_max_lines=sent_log_max_lines,
+    )
+
+
+def _summarise(card: dict[str, Any]) -> str:
+    """One-line human summary of a card via its registered type, fail-soft.
+
+    Reuses the same per-type ``summarise`` the CLI's ``push status`` uses so the
+    notification body matches what the agent sees. Falls back to a generic line
+    for an unknown type (forward-compatible).
+    """
+    from pocketshell.cards import get_card_type
+
+    card_type = card.get("type", "")
+    handler = get_card_type(card_type) if isinstance(card_type, str) else None
+    body = card.get("body", {})
+    state = card.get("state", {})
+    if handler is not None and isinstance(body, dict) and isinstance(state, dict):
+        try:
+            return handler.summarise(dict(body), dict(state))
+        except Exception:
+            pass
+    return f"{card_type or 'card'} updated"
+
+
+def _host_alias() -> str:
+    """Best-effort host identifier for the deep-link, never raising.
+
+    The host CLI does NOT know the app's host alias (the #859 research spike's
+    risk #2). The most reliable thing it can emit is its own resolvable
+    hostname, which the app matches against ``HostEntity.hostname`` /
+    ``HostEntity.name`` to route the tap to the right host's session feed. When
+    the match is ambiguous or absent the app falls back to its home screen — it
+    never opens the WRONG host.
+    """
+    try:
+        fqdn = socket.getfqdn().strip()
+        if fqdn and fqdn.lower() != "localhost":
+            return fqdn
+    except Exception:
+        pass
+    try:
+        return socket.gethostname().strip()
+    except Exception:
+        return ""
+
+
+def card_to_data(
+    session: str,
+    card: dict[str, Any],
+    *,
+    host: Optional[str] = None,
+) -> dict[str, str]:
+    """Map a card + its session to the app's ``agent_card`` data-message keys.
+
+    Keys (mirrors the app's ``AgentCardPushPayload`` contract):
+
+    - ``type`` = ``agent_card``
+    - ``session`` = the tmux session the card belongs to (deep-link target)
+    - ``host`` = best-effort host hostname for host resolution (may be empty)
+    - ``card_id`` = the card id
+    - ``card_type`` = e.g. ``checklist``
+    - ``title`` = the card title (falls back to a type-derived label)
+    - ``summary`` = the per-type one-line summary (e.g. ``checklist 1/3 checked``)
+    - ``card_key`` = the content-hash de-dup identity (also the app dedup key)
+    """
+    card_type = str(card.get("type", "") or "")
+    card_id = str(card.get("id", "") or "")
+    title = card.get("title")
+    title_str = title.strip() if isinstance(title, str) and title.strip() else _default_title(card_type)
+    summary = _summarise(card)
+    resolved_host = host if host is not None else _host_alias()
+    card_key = content_key(session, card)
+    return {
+        "type": AGENT_CARD_PUSH_TYPE,
+        "session": session,
+        "host": resolved_host or "",
+        "card_id": card_id,
+        "card_type": card_type,
+        "title": title_str,
+        "summary": summary,
+        "card_key": card_key,
+    }
+
+
+def _default_title(card_type: str) -> str:
+    if card_type == "checklist":
+        return "Checklist"
+    if card_type:
+        return card_type[:1].upper() + card_type[1:]
+    return "Card"
+
+
+def content_key(session: str, card: dict[str, Any]) -> str:
+    """Deterministic content key for a card (drives server-side de-dup).
+
+    Hashes the session + card id + type + title + body + state — NOT
+    ``updated_at`` (which changes on every push) — so an identical re-push
+    yields the SAME key (suppressed) while any content/state change yields a NEW
+    key (pushed). Stable across processes (``sort_keys``).
+    """
+    payload = {
+        "session": session,
+        "id": card.get("id"),
+        "type": card.get("type"),
+        "title": card.get("title"),
+        "body": card.get("body"),
+        "state": card.get("state"),
+    }
+    blob = json.dumps(payload, sort_keys=True, ensure_ascii=False)
+    digest = hashlib.sha256(blob.encode("utf-8")).hexdigest()[:16]
+    return f"{session}|{card.get('id')}|{digest}"
+
+
+def notify_card_pushed(
+    session: str,
+    card: dict[str, Any],
+    *,
+    card_paths: CardPaths,
+    host: Optional[str] = None,
+    sender: Optional["push_mod.FcmSender"] = None,
+    env: Optional[dict[str, str]] = None,
+    sent_log_max_lines: int = DEFAULT_SENT_LOG_MAX_LINES,
+) -> Optional[str]:
+    """Best-effort FCM push for a freshly upserted ``card``. Fail-soft.
+
+    Returns the ``card_key`` actually pushed this call, or ``None`` when push
+    isn't configured / nothing new was sent. NEVER raises — the ``push
+    checklist`` CLI call must succeed even when Firebase isn't set up.
+
+    Guards, in order (mirroring :func:`pocketshell.push.push_reset_events`):
+
+    1. No registered device token -> ``None``.
+    2. No service-account credential / no ``google.auth`` -> ``None`` (pre-S0).
+    3. Already pushed this exact content (de-dup) -> ``None``.
+    4. On a successful send: record the content key so it never re-POSTs.
+       On a failed send: leave it un-recorded so the next push RETRIES.
+    """
+    try:
+        usage_paths = resolve_usage_paths(env=env)
+        token = push_mod.read_token(usage_paths)
+        if token is None:
+            return None
+
+        if sender is None:
+            sa_path = push_mod._resolve_service_account_path(usage_paths, env=env)
+            if sa_path is None:
+                return None
+            sender = push_mod.FcmSender.from_service_account(sa_path)
+            if sender is None:
+                return None
+
+        data = card_to_data(session, card, host=host)
+        card_key = data["card_key"]
+        if card_key in sent_card_keys(card_paths):
+            return None
+        if sender.send_data_message(token=token, data=data):
+            _mark_sent(card_key, paths=card_paths, sent_log_max_lines=sent_log_max_lines)
+            return card_key
+        return None
+    except Exception:
+        # Absolute fail-soft backstop: a card push must never wedge the CLI.
+        return None

{pocketshell-0.4.17 → pocketshell-0.4.18}/src/pocketshell/cards.py

@@ -632,7 +632,17 @@ def register_push_card_commands(push_group: click.Group) -> None:
             build_kwargs={"items": parsed},
             preset_checked=preset_checked,
         )
-        path = upsert_card(target, card, paths=resolve_paths())
+        card_paths = resolve_paths()
+        path = upsert_card(target, card, paths=card_paths)
+        # Slice D (#859): fire a best-effort FCM push so the phone surfaces a
+        # heads-up notification opening this session's card feed. Fail-soft —
+        # imported lazily so a host without the push deps still pushes the card.
+        try:
+            from pocketshell.agent_card_push import notify_card_pushed
+
+            notify_card_pushed(target, card, card_paths=card_paths)
+        except Exception:
+            pass
         click.echo(
             f"checklist {card_id!r} ({len(parsed)} items) -> session {target!r} ({path})"
         )

pocketshell-0.4.18/tests/test_agent_card_push.py

@@ -0,0 +1,279 @@
+"""Unit tests for the agent-card FCM push trigger (epic #859, Slice D).
+
+Covers, per the issue acceptance criteria:
+ - `pocketshell push checklist` fires an `agent_card` FCM data push carrying
+   session / card_type / title / summary / card_key (REPRODUCE-FIRST: this is
+   the load-bearing success-path test — red before the trigger was wired).
+ - Fail-soft: no registered token -> no push, the CLI call still succeeds.
+ - Fail-soft: no service-account credential -> no push, CLI still succeeds.
+ - Server-side de-dup: re-pushing the SAME card does not re-POST; an UPDATED
+   card (new content key) DOES push.
+ - The data-message keys match the app's `AgentCardPushPayload` contract.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from click.testing import CliRunner
+
+from pocketshell import agent_card_push, cards as cards_mod, push as push_mod
+from pocketshell.cli import cli
+
+
+class _RecordingSender(push_mod.FcmSender):
+    """An FcmSender that records sends without touching the network."""
+
+    def __init__(self, *, ok: bool = True) -> None:
+        super().__init__(project_id="test-project", credentials=object())
+        self.ok = ok
+        self.calls: list[dict[str, Any]] = []
+
+    def send_data_message(self, *, token: str, data: dict[str, str]) -> bool:
+        self.calls.append({"token": token, "data": dict(data)})
+        return self.ok
+
+
+def _card_paths(tmp_path: Path) -> cards_mod.CardPaths:
+    return cards_mod.CardPaths(cards_dir=tmp_path / "cards")
+
+
+def _checklist_card(title: str = "Deploy", checked: list[str] | None = None) -> dict[str, Any]:
+    return cards_mod.build_card(
+        card_type="checklist",
+        card_id="checklist",
+        title=title,
+        build_kwargs={
+            "items": [
+                {"id": "build-0", "text": "build"},
+                {"id": "ship-1", "text": "ship"},
+            ]
+        },
+        preset_checked=checked or [],
+    )
+
+
+def _state_env(tmp_path: Path, *, session: str = "demo", with_token: bool = True) -> dict[str, str]:
+    """CLI/trigger env: relocate BOTH the cards store and the usage state dir.
+
+    `XDG_STATE_HOME` relocates the usage dir (where the device token lives);
+    `POCKETSHELL_CARDS_DIR` relocates the cards store + its sent-log.
+    """
+    state_home = tmp_path / "state"
+    env = {
+        "XDG_STATE_HOME": str(state_home),
+        "POCKETSHELL_CARDS_DIR": str(tmp_path / "cards"),
+        "TMUX": f"/tmp/x,1,0 {session}",
+    }
+    if with_token:
+        usage_paths = push_mod.resolve_paths(env=env)
+        push_mod.register_token("device-token-abc", paths=usage_paths)
+    return env
+
+
+# ---------------------------------------------------------------------------
+# notify_card_pushed — success path + payload contract (REPRODUCE-FIRST)
+# ---------------------------------------------------------------------------
+
+
+def test_notify_card_pushed_sends_agent_card_data_message(tmp_path: Path) -> None:
+    env = _state_env(tmp_path)
+    sender = _RecordingSender()
+    card = _checklist_card(checked=["build-0"])
+
+    card_key = agent_card_push.notify_card_pushed(
+        "demo",
+        card,
+        card_paths=_card_paths(tmp_path),
+        host="agent-box.example",
+        sender=sender,
+        env=env,
+    )
+
+    assert card_key is not None
+    assert len(sender.calls) == 1
+    data = sender.calls[0]["data"]
+    # The app's AgentCardPushPayload contract.
+    assert data["type"] == "agent_card"
+    assert data["session"] == "demo"
+    assert data["host"] == "agent-box.example"
+    assert data["card_id"] == "checklist"
+    assert data["card_type"] == "checklist"
+    assert data["title"] == "Deploy"
+    assert data["summary"] == "checklist 1/2 checked"
+    assert data["card_key"] == card_key
+    assert sender.calls[0]["token"] == "device-token-abc"
+
+
+def test_notify_card_pushed_default_host_is_resolvable_hostname(tmp_path: Path) -> None:
+    env = _state_env(tmp_path)
+    sender = _RecordingSender()
+    agent_card_push.notify_card_pushed(
+        "demo", _checklist_card(), card_paths=_card_paths(tmp_path), sender=sender, env=env
+    )
+    # host best-effort: a non-None string (may be empty in an exotic sandbox,
+    # but the KEY is always present so the app can parse it).
+    assert "host" in sender.calls[0]["data"]
+
+
+# ---------------------------------------------------------------------------
+# Fail-soft guards
+# ---------------------------------------------------------------------------
+
+
+def test_notify_card_pushed_no_token_is_noop(tmp_path: Path) -> None:
+    env = _state_env(tmp_path, with_token=False)
+    sender = _RecordingSender()
+    result = agent_card_push.notify_card_pushed(
+        "demo", _checklist_card(), card_paths=_card_paths(tmp_path), sender=sender, env=env
+    )
+    assert result is None
+    assert sender.calls == []
+
+
+def test_notify_card_pushed_no_credential_is_noop(tmp_path: Path) -> None:
+    # Token present but NO sender passed and NO service-account JSON on disk ->
+    # FcmSender.from_service_account path can't resolve -> no-op (pre-S0 host).
+    env = _state_env(tmp_path)
+    result = agent_card_push.notify_card_pushed(
+        "demo", _checklist_card(), card_paths=_card_paths(tmp_path), sender=None, env=env
+    )
+    assert result is None
+
+
+# ---------------------------------------------------------------------------
+# Server-side de-dup
+# ---------------------------------------------------------------------------
+
+
+def test_notify_card_pushed_dedups_identical_repush(tmp_path: Path) -> None:
+    env = _state_env(tmp_path)
+    paths = _card_paths(tmp_path)
+    sender = _RecordingSender()
+    card = _checklist_card(checked=["build-0"])
+
+    first = agent_card_push.notify_card_pushed("demo", card, card_paths=paths, sender=sender, env=env)
+    # An identical re-push (same content; build_card bumps updated_at but the
+    # content key ignores it) must NOT re-POST.
+    second = agent_card_push.notify_card_pushed("demo", card, card_paths=paths, sender=sender, env=env)
+
+    assert first is not None
+    assert second is None
+    assert len(sender.calls) == 1
+
+
+def test_notify_card_pushed_updated_card_pushes_again(tmp_path: Path) -> None:
+    env = _state_env(tmp_path)
+    paths = _card_paths(tmp_path)
+    sender = _RecordingSender()
+
+    agent_card_push.notify_card_pushed(
+        "demo", _checklist_card(checked=[]), card_paths=paths, sender=sender, env=env
+    )
+    # A genuine state change (an item now checked) is a NEW content key -> push.
+    updated = agent_card_push.notify_card_pushed(
+        "demo", _checklist_card(checked=["build-0"]), card_paths=paths, sender=sender, env=env
+    )
+
+    assert updated is not None
+    assert len(sender.calls) == 2
+
+
+def test_notify_card_pushed_failed_send_not_marked_retries(tmp_path: Path) -> None:
+    env = _state_env(tmp_path)
+    paths = _card_paths(tmp_path)
+    card = _checklist_card()
+
+    failing = _RecordingSender(ok=False)
+    assert (
+        agent_card_push.notify_card_pushed("demo", card, card_paths=paths, sender=failing, env=env)
+        is None
+    )
+    # A later attempt with a now-working sender must RETRY (the first failure
+    # left the key un-marked).
+    ok = _RecordingSender(ok=True)
+    assert (
+        agent_card_push.notify_card_pushed("demo", card, card_paths=paths, sender=ok, env=env)
+        is not None
+    )
+    assert len(ok.calls) == 1
+
+
+def test_content_key_ignores_updated_at(tmp_path: Path) -> None:
+    a = _checklist_card()
+    b = dict(a)
+    b["updated_at"] = "2099-01-01T00:00:00Z"  # different timestamp, same content
+    assert agent_card_push.content_key("demo", a) == agent_card_push.content_key("demo", b)
+
+
+def test_content_key_changes_on_state_change(tmp_path: Path) -> None:
+    a = _checklist_card(checked=[])
+    b = _checklist_card(checked=["build-0"])
+    assert agent_card_push.content_key("demo", a) != agent_card_push.content_key("demo", b)
+
+
+# ---------------------------------------------------------------------------
+# CLI integration — `push checklist` fires the trigger, fail-soft otherwise
+# ---------------------------------------------------------------------------
+
+
+def test_cli_push_checklist_fires_trigger_when_configured(tmp_path: Path, monkeypatch: Any) -> None:
+    env = _state_env(tmp_path)
+    sender = _RecordingSender()
+    monkeypatch.setattr(cards_mod, "_tmux_current_session", lambda: "demo")
+    # Force the lazy trigger to use our recording sender (no real Firebase).
+    real_notify = agent_card_push.notify_card_pushed
+
+    def _notify(session, card, **kwargs):  # type: ignore[no-untyped-def]
+        kwargs.setdefault("sender", sender)
+        kwargs.setdefault("env", env)
+        return real_notify(session, card, **kwargs)
+
+    monkeypatch.setattr(agent_card_push, "notify_card_pushed", _notify)
+
+    runner = CliRunner()
+    result = runner.invoke(
+        cli,
+        ["push", "checklist", "--title", "Release"],
+        input="- [ ] build\n- [x] ship\n",
+        env=env,
+    )
+    assert result.exit_code == 0, result.output
+    assert len(sender.calls) == 1
+    data = sender.calls[0]["data"]
+    assert data["type"] == "agent_card"
+    assert data["session"] == "demo"
+    assert data["card_type"] == "checklist"
+
+
+def test_cli_push_checklist_succeeds_when_push_unconfigured(tmp_path: Path, monkeypatch: Any) -> None:
+    # No token registered -> the trigger no-ops, but the CLI call STILL succeeds
+    # (the agent's `push checklist` must never break on an unconfigured host).
+    env = _state_env(tmp_path, with_token=False)
+    monkeypatch.setattr(cards_mod, "_tmux_current_session", lambda: "demo")
+    runner = CliRunner()
+    result = runner.invoke(
+        cli,
+        ["push", "checklist", "--title", "Release"],
+        input="- [ ] build\n",
+        env=env,
+    )
+    assert result.exit_code == 0, result.output
+    assert "checklist" in result.output
+
+
+def test_cli_push_checklist_succeeds_even_if_trigger_raises(tmp_path: Path, monkeypatch: Any) -> None:
+    # The trigger is best-effort: even a bug that raises must not fail the CLI.
+    env = _state_env(tmp_path, with_token=False)
+    monkeypatch.setattr(cards_mod, "_tmux_current_session", lambda: "demo")
+
+    def _boom(*_a: Any, **_k: Any) -> None:
+        raise RuntimeError("boom")
+
+    monkeypatch.setattr(agent_card_push, "notify_card_pushed", _boom)
+    runner = CliRunner()
+    result = runner.invoke(
+        cli, ["push", "checklist"], input="- [ ] build\n", env=env
+    )
+    assert result.exit_code == 0, result.output