pocketshell 0.4.14__tar.gz → 0.4.17__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pocketshell
-Version: 0.4.14
+Version: 0.4.17
 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.14 → pocketshell-0.4.17}/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.14"
+version = "0.4.17"
 description = "Unified server-side Python utility for the PocketShell Android client."
 readme = "README.md"
 requires-python = ">=3.11"

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

@@ -360,6 +360,62 @@ register_card_type(
 )
 
 
+# ---------------------------------------------------------------------------
+# note card type (#859 Slice B — proves the registry is genuinely generic)
+# ---------------------------------------------------------------------------
+#
+# A ``note`` is a non-interactive message the agent hands the human ("deploy
+# finished", "found a flaky test"). Its only interaction is mark-as-read, so the
+# agent can tell from ``push status`` whether the human has seen it. Registering
+# it is exactly one ``register_card_type`` call + a ``push note`` verb — no new
+# transport, no change to the store/read/write/upsert path. That is the whole
+# point of the registry: a second real type is additive.
+
+# Default note card id used when ``--id`` is omitted (one default note per
+# session unless the agent names them — mirrors DEFAULT_CHECKLIST_ID).
+DEFAULT_NOTE_ID = "note"
+
+
+def _note_build_body(*, text: str, **_: Any) -> dict[str, Any]:
+    """Build the note ``body`` — ``{"text": <message>}``."""
+    return {"text": text}
+
+
+def _note_initial_state(_body: dict[str, Any]) -> dict[str, Any]:
+    """A fresh note is unread."""
+    return {"read": False, "read_at": None}
+
+
+def _note_apply_interaction(
+    body: dict[str, Any],
+    state: dict[str, Any],
+    interaction: Mapping[str, Any],
+) -> dict[str, Any]:
+    """Mark a note read/unread.
+
+    ``interaction = {"read": bool}``. ``read`` defaults to True (mark read).
+    ``read_at`` records when it was first read (cleared on unread) so the agent
+    can see acknowledgement timing via ``push status``.
+    """
+    read = bool(interaction.get("read", True))
+    return {"read": read, "read_at": _now_iso() if read else None}
+
+
+def _note_summarise(body: dict[str, Any], state: dict[str, Any]) -> str:
+    return "note: read" if state.get("read") else "note: unread"
+
+
+register_card_type(
+    CardType(
+        name="note",
+        build_body=_note_build_body,
+        initial_state=_note_initial_state,
+        apply_interaction=_note_apply_interaction,
+        summarise=_note_summarise,
+    )
+)
+
+
 # ---------------------------------------------------------------------------
 # Store read/write
 # ---------------------------------------------------------------------------
@@ -661,3 +717,71 @@ def register_push_card_commands(push_group: click.Group) -> None:
         state = card.get("state", {}) if isinstance(card.get("state"), Mapping) else {}
         summary = handler.summarise(dict(body), dict(state)) if handler else ""
         click.echo(f"{card_id}: {summary}")
+
+    @push_group.command("note")
+    @click.option("--title", "title", default=None, help="Human title for the note card.")
+    @click.option(
+        "--id",
+        "card_id",
+        default=DEFAULT_NOTE_ID,
+        help=f"Card id (default {DEFAULT_NOTE_ID!r}; one default note per session).",
+    )
+    @click.option(
+        "--text",
+        "text",
+        default=None,
+        help="The note body. Alternative to piping the message on stdin.",
+    )
+    @click.option("--session", "session", default=None, help="Override the auto-detected tmux session.")
+    def push_note(
+        title: Optional[str],
+        card_id: str,
+        text: Optional[str],
+        session: Optional[str],
+    ) -> None:
+        """Create/replace the session's note card from --text or piped stdin.
+
+        A note is a non-interactive message the human marks read (``push read``).
+        The session is auto-detected from ``$TMUX`` (override with ``--session``).
+        A re-push fully replaces the card of that id (hard-cut, D22).
+        """
+        target = _require_session(session)
+        if text is not None and text.strip():
+            body_text = text.strip()
+        else:
+            stdin_text = "" if sys.stdin is None or sys.stdin.isatty() else sys.stdin.read()
+            body_text = stdin_text.strip()
+        if not body_text:
+            raise click.ClickException(
+                "empty note: pass --text or pipe the message on stdin."
+            )
+        card = build_card(
+            card_type="note",
+            card_id=card_id,
+            title=title,
+            build_kwargs={"text": body_text},
+        )
+        path = upsert_card(target, card, paths=resolve_paths())
+        click.echo(f"note {card_id!r} -> session {target!r} ({path})")
+
+    @push_group.command("read")
+    @click.option("--id", "card_id", required=True, help="The note card id.")
+    @click.option("--read/--unread", "read", default=True, help="Mark read (default) or unread.")
+    @click.option("--session", "session", default=None, help="Override the auto-detected tmux session.")
+    def push_read(card_id: str, read: bool, session: Optional[str]) -> None:
+        """Set a note's read state (this is what the app's "mark read" calls)."""
+        target = _require_session(session)
+        try:
+            card = apply_interaction(
+                target,
+                card_id,
+                {"read": read},
+                paths=resolve_paths(),
+            )
+        except ValueError as exc:
+            raise click.ClickException(str(exc))
+        handler = get_card_type(card.get("type", ""))
+        body = card.get("body", {}) if isinstance(card.get("body"), Mapping) else {}
+        state = card.get("state", {}) if isinstance(card.get("state"), Mapping) else {}
+        summary = handler.summarise(dict(body), dict(state)) if handler else ""
+        click.echo(f"{card_id}: {summary}")

{pocketshell-0.4.14 → pocketshell-0.4.17}/tests/test_cards.py

@@ -389,3 +389,139 @@ def test_cli_check_unknown_item_errors(tmp_path: Path) -> None:
     )
     assert res.exit_code != 0
     assert "unknown item" in res.output
+
+
+# ----- note card type (#859 Slice B — registry is genuinely generic) ----
+
+
+def test_note_card_type_is_registered() -> None:
+    """AC: the host registers a REAL `note` CardType (not just the stub test)."""
+    handler = cards_mod.get_card_type("note")
+    assert handler is not None
+    assert handler.name == "note"
+
+
+def test_build_upsert_read_note(tmp_path: Path) -> None:
+    """AC: note `body={text}`, `state={read:false, read_at:None}` round-trips."""
+    paths = _paths(tmp_path)
+    card = cards_mod.build_card(
+        card_type="note",
+        card_id="note",
+        title="Heads up",
+        build_kwargs={"text": "deploy finished"},
+    )
+    cards_mod.upsert_card("demo", card, paths=paths)
+    got = cards_mod.read_cards("demo", paths=paths)
+    assert len(got) == 1
+    assert got[0]["type"] == "note"
+    assert got[0]["title"] == "Heads up"
+    assert got[0]["body"] == {"text": "deploy finished"}
+    assert got[0]["state"] == {"read": False, "read_at": None}
+
+
+def test_note_apply_interaction_marks_read_and_unread(tmp_path: Path) -> None:
+    """AC: mark-as-read interaction sets read + read_at; unread clears read_at."""
+    paths = _paths(tmp_path)
+    card = cards_mod.build_card(
+        card_type="note", card_id="note", title=None,
+        build_kwargs={"text": "hi"},
+    )
+    cards_mod.upsert_card("demo", card, paths=paths)
+
+    read = cards_mod.apply_interaction("demo", "note", {"read": True}, paths=paths)
+    assert read["state"]["read"] is True
+    assert read["state"]["read_at"]  # a timestamp, not None
+
+    unread = cards_mod.apply_interaction("demo", "note", {"read": False}, paths=paths)
+    assert unread["state"]["read"] is False
+    assert unread["state"]["read_at"] is None
+
+
+def test_note_and_checklist_coexist_in_one_session(tmp_path: Path) -> None:
+    """The store is type-agnostic: a note + a checklist live side by side."""
+    paths = _paths(tmp_path)
+    checklist = cards_mod.build_card(
+        card_type="checklist", card_id="checklist", title="Deploy",
+        build_kwargs={"items": [{"id": "build-0", "text": "build"}]},
+    )
+    note = cards_mod.build_card(
+        card_type="note", card_id="note", title=None,
+        build_kwargs={"text": "fyi"},
+    )
+    cards_mod.upsert_card("demo", checklist, paths=paths)
+    cards_mod.upsert_card("demo", note, paths=paths)
+    got = cards_mod.read_cards("demo", paths=paths)
+    assert {c["type"] for c in got} == {"checklist", "note"}
+
+
+def test_cli_note_set_get_read_status_flow(tmp_path: Path) -> None:
+    """AC: push note (stdin) → get --json → read → status reflects read."""
+    runner = CliRunner()
+    env = _env(tmp_path)
+
+    res = runner.invoke(
+        cli,
+        ["push", "note", "--title", "Heads up", "--session", "demo"],
+        input="deploy finished\n",
+        env=env,
+    )
+    assert res.exit_code == 0, res.output
+    assert "note 'note'" in res.output
+
+    res = runner.invoke(cli, ["push", "get", "--json", "--session", "demo"], env=env)
+    assert res.exit_code == 0, res.output
+    payload = json.loads(res.output)
+    card = payload["cards"][0]
+    assert card["type"] == "note"
+    assert card["title"] == "Heads up"
+    assert card["body"]["text"] == "deploy finished"
+    assert card["state"]["read"] is False
+
+    # Human marks it read (this is what the app's "mark read" calls).
+    res = runner.invoke(
+        cli, ["push", "read", "--id", "note", "--session", "demo"], env=env
+    )
+    assert res.exit_code == 0, res.output
+    assert "note: read" in res.output
+
+    # Agent reads the acknowledgement via status.
+    res = runner.invoke(cli, ["push", "status", "--json", "--session", "demo"], env=env)
+    assert res.exit_code == 0, res.output
+    status = json.loads(res.output)
+    assert status["status"][0]["state"]["read"] is True
+
+    res = runner.invoke(cli, ["push", "status", "--session", "demo"], env=env)
+    assert res.exit_code == 0, res.output
+    assert "note: read" in res.output
+
+
+def test_cli_note_text_via_flag(tmp_path: Path) -> None:
+    runner = CliRunner()
+    env = _env(tmp_path)
+    res = runner.invoke(
+        cli, ["push", "note", "--text", "found a flaky test", "--session", "demo"],
+        env=env,
+    )
+    assert res.exit_code == 0, res.output
+    got = cards_mod.read_cards("demo", paths=_paths(tmp_path))
+    assert got[0]["body"]["text"] == "found a flaky test"
+
+
+def test_cli_note_empty_errors(tmp_path: Path) -> None:
+    runner = CliRunner()
+    env = _env(tmp_path)
+    res = runner.invoke(
+        cli, ["push", "note", "--session", "demo"], input="", env=env
+    )
+    assert res.exit_code != 0
+    assert "empty note" in res.output
+
+
+def test_cli_read_unknown_card_errors(tmp_path: Path) -> None:
+    runner = CliRunner()
+    env = _env(tmp_path)
+    res = runner.invoke(
+        cli, ["push", "read", "--id", "ghost", "--session", "demo"], env=env
+    )
+    assert res.exit_code != 0
+    assert "no card" in res.output

{pocketshell-0.4.14 → pocketshell-0.4.17}/uv.lock

@@ -3,7 +3,8 @@ revision = 3
 requires-python = ">=3.11"
 
 [options]
-exclude-newer = "2026-12-31T23:00:00Z"
+exclude-newer = "2026-06-18T14:08:51.166593044Z"
+exclude-newer-span = "P7D"
 
 [[package]]
 name = "annotated-doc"
@@ -314,7 +315,7 @@ wheels = [
 
 [[package]]
 name = "pocketshell"
-version = "0.4.14"
+version = "0.4.16"
 source = { editable = "." }
 dependencies = [
     { name = "click" },