Merge branch 'master' into claude/plain-run-shell-ux-wdcwrh

Author: davegaeddert

.claude/rules/plain-code.md

@@ -28,6 +28,7 @@ Runs ruff, ty (type checking), oxlint/oxfmt, and annotation coverage checks with
 
 ## Code Style
 
-- Add `from __future__ import annotations` at the top of Python files
+- Functions with more than one parameter should make them keyword-only (`def send(*, to, subject)`) — explicit call sites, safer refactors
+- Don't accept or pass through `**kwargs` blindly — spell out real parameters so type checking works at call sites
 - Keep imports at the top of the file unless avoiding circular imports
 - Don't include args/returns in docstrings if already type annotated

.claude/rules/plain.md

@@ -83,7 +83,8 @@ If the exception propagates out of the span context, the SDK auto-records and se
 - View 5xx attachment — `plain/views/base.py:_respond_to_exception` (records on the SERVER span via `_finalize_span`)
 - Job enqueue — PRODUCER (`plain-jobs/jobs/jobs.py`)
 - Job execute — CONSUMER (`plain-jobs/jobs/models.py`), plus a fallback CONSUMER span in `plain-jobs/jobs/workers.py:process_job` that catches lookup-time failures before `run()` is reached
-- Worker maintenance loop — CONSUMER (`plain-jobs/jobs/workers.py`)
+- Worker maintenance loop — CONSUMER (`plain-jobs/jobs/workers.py`), opened only on ticks where a maintenance task is due — fully idle ticks emit no spans at all
+- Worker claim/heartbeat failures — one-off `claim job` / `worker heartbeat` CONSUMER error spans via `emit_error_consumer_span` (`plain-jobs/jobs/otel.py`); the claim transaction, heartbeat writes, gauge queries, and done-callback bookkeeping are otherwise untraced (`plain.postgres.otel.suppress_db_tracing`)
 - Chore execution — CONSUMER (`plain/cli/chores.py`)
 - MCP RPC dispatch — SERVER (`plain-mcp/mcp/views.py`)
 

plain-admin/tests/app/urls.py

@@ -1,5 +1,6 @@
 from plain.admin.urls import AdminRouter
 from plain.assets.urls import AssetsRouter
+from plain.http import Response
 from plain.urls import Router, include, path
 from plain.views import View
 
@@ -9,6 +10,13 @@ def get(self):
         return "Login!"
 
 
+class WhoView(View):
+    """A plain 200 endpoint for reading the effective request user in tests."""
+
+    def get(self):
+        return Response("ok")
+
+
 class LogoutView(View):
     def get(self):
         return "Logout!"
@@ -21,4 +29,5 @@ class AppRouter(Router):
         include("assets", AssetsRouter),
         path("login", LoginView, name="login"),
         path("logout", LogoutView, name="logout"),
+        path("whoami", WhoView, name="whoami"),
     ]

plain-admin/tests/public/test_dates.py

@@ -0,0 +1,68 @@
+"""Tests for the admin date-range helpers used by cards and charts."""
+
+from __future__ import annotations
+
+import datetime
+
+import pytest
+
+from plain.admin.dates import DatetimeRange, DatetimeRangeAliases
+
+
+def _dt(y, m, d, **kw):
+    return datetime.datetime(y, m, d, tzinfo=datetime.UTC, **kw)
+
+
+def test_as_tuple_and_total_days():
+    r = DatetimeRange(start=_dt(2024, 1, 1), end=_dt(2024, 1, 4))
+    assert r.as_tuple() == (_dt(2024, 1, 1), _dt(2024, 1, 4))
+    assert r.total_days() == 3
+
+
+def test_iter_days_is_inclusive():
+    r = DatetimeRange(start=_dt(2024, 1, 1), end=_dt(2024, 1, 3))
+    days = list(r.iter_days())
+    assert days == [
+        datetime.date(2024, 1, 1),
+        datetime.date(2024, 1, 2),
+        datetime.date(2024, 1, 3),
+    ]
+
+
+def test_contains_checks_bounds():
+    r = DatetimeRange(start=_dt(2024, 1, 1), end=_dt(2024, 1, 31))
+    assert _dt(2024, 1, 15) in r
+    assert _dt(2023, 12, 31) not in r
+    assert _dt(2024, 2, 1) not in r
+
+
+def test_equality_and_hash():
+    a = DatetimeRange(start=_dt(2024, 1, 1), end=_dt(2024, 1, 2))
+    b = DatetimeRange(start=_dt(2024, 1, 1), end=_dt(2024, 1, 2))
+    c = DatetimeRange(start=_dt(2024, 1, 1), end=_dt(2024, 1, 3))
+    assert a == b
+    assert a != c
+    assert hash(a) == hash(b)
+
+
+def test_from_value_round_trip():
+    assert DatetimeRangeAliases.from_value("Today") is DatetimeRangeAliases.TODAY
+
+
+def test_from_value_rejects_unknown():
+    with pytest.raises(ValueError, match="not a valid value"):
+        DatetimeRangeAliases.from_value("Some Nonsense Range")
+
+
+def test_to_range_today_spans_a_single_day():
+    r = DatetimeRangeAliases.to_range("Today")
+    assert (r.start.hour, r.start.minute, r.start.second) == (0, 0, 0)
+    assert (r.end.hour, r.end.minute) == (23, 59)
+    assert r.start.date() == r.end.date()
+    assert r.total_days() == 0
+
+
+def test_to_range_accepts_enum_member():
+    r = DatetimeRangeAliases.to_range(DatetimeRangeAliases.SINCE_30_DAYS_AGO)
+    # "Since 30 days ago" runs from 30 days back through today.
+    assert 29 <= r.total_days() <= 30

plain-admin/tests/public/test_impersonate.py

@@ -0,0 +1,75 @@
+"""Security tests for admin user impersonation.
+
+Impersonation lets an allowed user (by default, an admin) act as another
+user. The guardrails that matter: only allowed users can start it, admins
+can't be impersonated, and stopping restores the original user.
+"""
+
+from __future__ import annotations
+
+from app.users.models import User
+
+from plain.test import Client
+
+
+def test_admin_can_impersonate_regular_user(db):
+    admin = User.query.create(username="admin", is_admin=True)
+    target = User.query.create(username="target", is_admin=False)
+
+    client = Client()
+    client.force_login(admin)
+
+    started = client.get(f"/admin/impersonate/start/{target.id}")
+    assert started.status_code == 302
+
+    # Subsequent requests are now served as the target user.
+    response = client.get("/whoami")
+    assert response.user.id == target.id
+
+
+def test_stopping_impersonation_restores_original_user(db):
+    admin = User.query.create(username="admin", is_admin=True)
+    target = User.query.create(username="target", is_admin=False)
+
+    client = Client()
+    client.force_login(admin)
+    client.get(f"/admin/impersonate/start/{target.id}")
+    assert client.get("/whoami").user.id == target.id
+
+    stopped = client.get("/admin/impersonate/stop")
+    assert stopped.status_code == 302
+
+    # Back to acting as the admin.
+    assert client.get("/whoami").user.id == admin.id
+
+
+def test_non_admin_cannot_start_impersonation(db):
+    regular = User.query.create(username="regular", is_admin=False)
+    target = User.query.create(username="target", is_admin=False)
+
+    client = Client()
+    client.force_login(regular)
+
+    started = client.get(f"/admin/impersonate/start/{target.id}")
+    assert started.status_code == 403
+
+    # The effective user is unchanged — no impersonation took hold.
+    assert client.get("/whoami").user.id == regular.id
+
+
+def test_admin_users_cannot_be_impersonated(db):
+    admin = User.query.create(username="admin", is_admin=True)
+    other_admin = User.query.create(username="other_admin", is_admin=True)
+
+    client = Client()
+    client.force_login(admin)
+
+    # The start view sets the session marker, but the middleware refuses to
+    # swap to an admin target and clears it.
+    assert client.get(f"/admin/impersonate/start/{other_admin.id}").status_code == 302
+
+    blocked = client.get("/whoami")
+    assert blocked.status_code == 403
+
+    # After the refusal the marker is cleared, so normal requests resume.
+    assert client.get("/whoami").user.id == admin.id

plain-auth/tests/app/urls.py

@@ -1,5 +1,9 @@
+from app.users.models import User
+
+from plain.auth import login, logout
 from plain.auth.views import AuthView
 from plain.http import Response
+from plain.sessions import get_request_session
 from plain.urls import Router, path
 from plain.views import View
 
@@ -9,6 +13,39 @@ def get(self):
         return Response("login")
 
 
+class VisitView(View):
+    """Write to the anonymous session so a session cookie is issued."""
+
+    def get(self):
+        get_request_session(self.request)["visited"] = "yes"
+        return Response("visited")
+
+
+class SessionLoginView(View):
+    """Log a user in through the real ``login()`` flow."""
+
+    def post(self):
+        user = User.query.get(id=self.request.form_data["user_id"])
+        login(self.request, user)
+        return Response("logged in")
+
+
+class SessionLogoutView(View):
+    """Log the current user out through the real ``logout()`` flow."""
+
+    def post(self):
+        logout(self.request)
+        return Response("logged out")
+
+
+class WhoView(AuthView):
+    login_required = True
+
+    def get(self):
+        # login_required guarantees an authenticated user here.
+        return Response(self.user.username)  # ty: ignore[unresolved-attribute]
+
+
 class ProtectedView(AuthView):
     login_required = True
 
@@ -42,6 +79,10 @@ class AppRouter(Router):
     namespace = ""
     urls = [
         path("login", LoginView, name="login"),
+        path("visit", VisitView, name="visit"),
+        path("session-login", SessionLoginView, name="session_login"),
+        path("session-logout", SessionLogoutView, name="session_logout"),
+        path("whoami", WhoView, name="whoami"),
         path("protected", ProtectedView, name="protected"),
         path("open", OpenView, name="open"),
         path("admin", AdminView, name="admin"),

plain-auth/tests/public/test_login_flow.py

@@ -0,0 +1,80 @@
+"""End-to-end tests for the real ``login()`` / ``logout()`` session flow.
+
+These exercise the functions users actually call from their login views —
+covering session persistence across requests, session-fixation protection,
+logout, and safe user-switching — rather than the test-only ``force_login``
+shortcut.
+"""
+
+from app.users.models import User
+
+from plain.runtime import settings
+from plain.test import Client
+
+SESSION_COOKIE = settings.SESSION_COOKIE_NAME
+
+
+def _session_cookie(client):
+    morsel = client.cookies.get(SESSION_COOKIE)
+    return morsel.value if morsel else None
+
+
+def test_login_persists_across_requests(db):
+    user = User.query.create(username="alice")
+    client = Client()
+
+    # A protected page is unreachable before logging in.
+    assert client.get("/whoami").status_code == 302
+
+    resp = client.post("/session-login", data={"user_id": user.id})
+    assert resp.status_code == 200
+
+    # The same client is now recognized on a later, separate request.
+    resp = client.get("/whoami")
+    assert resp.status_code == 200
+    assert resp.content == b"alice"
+
+
+def test_login_rotates_session_key(db):
+    """Logging in from an anonymous session issues a new session key
+    (session-fixation protection)."""
+    user = User.query.create(username="bob")
+    client = Client()
+
+    # Establish an anonymous session (with data) so a cookie already exists.
+    client.get("/visit")
+    anon_key = _session_cookie(client)
+    assert anon_key is not None
+
+    client.post("/session-login", data={"user_id": user.id})
+    logged_in_key = _session_cookie(client)
+
+    assert logged_in_key is not None
+    assert logged_in_key != anon_key
+
+
+def test_logout_flushes_session(db):
+    user = User.query.create(username="carol")
+    client = Client()
+
+    client.post("/session-login", data={"user_id": user.id})
+    assert client.get("/whoami").status_code == 200
+
+    resp = client.post("/session-logout")
+    assert resp.status_code == 200
+
+    # After logout the protected page redirects to login again.
+    assert client.get("/whoami").status_code == 302
+
+
+def test_login_as_different_user_replaces_session(db):
+    """Logging in as a second user must not retain the first user's session."""
+    first = User.query.create(username="first")
+    second = User.query.create(username="second")
+    client = Client()
+
+    client.post("/session-login", data={"user_id": first.id})
+    assert client.get("/whoami").content == b"first"
+
+    client.post("/session-login", data={"user_id": second.id})
+    assert client.get("/whoami").content == b"second"

plain-cloud/pyproject.toml

@@ -8,6 +8,9 @@ readme = "README.md"
 requires-python = ">=3.13"
 dependencies = ["click>=8.0.0", "httpx>=0.27.0", "keyring>=24.0.0"]
 
+[dependency-groups]
+dev = ["pytest"]
+
 [project.scripts]
 plain-cloud = "plain.cloud.cli:cli"
 plaincloud = "plain.cloud.cli:cli"

plain-code/plain/code/agents/.claude/rules/plain-code.md

@@ -28,6 +28,7 @@ Runs ruff, ty (type checking), oxlint/oxfmt, and annotation coverage checks with
 
 ## Code Style
 
-- Add `from __future__ import annotations` at the top of Python files
+- Functions with more than one parameter should make them keyword-only (`def send(*, to, subject)`) — explicit call sites, safer refactors
+- Don't accept or pass through `**kwargs` blindly — spell out real parameters so type checking works at call sites
 - Keep imports at the top of the file unless avoiding circular imports
 - Don't include args/returns in docstrings if already type annotated

plain-dev/plain/dev/core.py

@@ -202,6 +202,12 @@ def run(self, *, reinstall_ssl: bool = False) -> int:
         self.add_entrypoints()
         self.add_pyproject_run()
 
+        # The status bar is invisible in piped output and the log file,
+        # so print the URLs as regular lines too.
+        self.poncho.system_print(f"Server running at {self.url}\n")
+        if self.tunnel_url:
+            self.poncho.system_print(f"Tunnel running at {self.tunnel_url}\n")
+
         try:
             # Start processes we know about and block the main thread
             self.poncho.loop()