From 1a9201cb91fd3d7b611b80c8d52840b3846641bd Mon Sep 17 00:00:00 2001 From: retoor Date: Sun, 15 Nov 2026 01:50:50 +0100 Subject: [PATCH] Admin pages: one shared specification, builders, fragments, caps and live refresh Adds admin_sections registry, shared admin partials, WorkspaceList, admin CLAUDE.md spec, capped node/flag listings, and api/unit tests enforcing the spec. Co-Authored-By: Claude Sonnet 5.5 --- devplacepy/admin_sections.py | 38 ++ devplacepy/database/nodes.py | 13 +- devplacepy/responses.py | 13 +- devplacepy/routers/CLAUDE.md | 4 + devplacepy/routers/admin/CLAUDE.md | 82 +++++ devplacepy/routers/admin/_shared.py | 4 + devplacepy/routers/admin/aiusage.py | 56 ++- devplacepy/routers/admin/backups.py | 8 +- devplacepy/routers/admin/communities.py | 9 +- devplacepy/routers/admin/containers.py | 21 +- devplacepy/routers/admin/devii_tasks.py | 32 +- devplacepy/routers/admin/gateway_configs.py | 62 +++- devplacepy/routers/admin/issues.py | 17 +- devplacepy/routers/admin/nodes.py | 6 +- devplacepy/routers/admin/services.py | 44 ++- devplacepy/routers/admin/statistics.py | 61 +++- devplacepy/routers/admin/workspaces.py | 48 ++- devplacepy/schemas/__init__.py | 3 + devplacepy/schemas/admin.py | 34 ++ devplacepy/schemas/backups.py | 1 + devplacepy/schemas/containers.py | 3 + devplacepy/schemas/statistics.py | 6 + devplacepy/services/community/store.py | 8 +- devplacepy/services/statistics/build.py | 83 +++++ devplacepy/services/statistics/tabs_data.py | 4 +- devplacepy/static/css/CLAUDE.md | 2 + devplacepy/static/css/admin.css | 23 ++ devplacepy/static/css/gateway.css | 4 + devplacepy/static/css/planning.css | 4 - devplacepy/static/css/services.css | 20 -- devplacepy/static/js/AdminCommunity.js | 5 +- devplacepy/static/js/AdminNodes.js | 4 +- devplacepy/static/js/AiUsageMonitor.js | 250 +------------ devplacepy/static/js/BackupMonitor.js | 232 ++---------- devplacepy/static/js/CLAUDE.md | 2 + devplacepy/static/js/ContainerList.js | 35 +- devplacepy/static/js/GatewayStats.js | 116 ++---- devplacepy/static/js/Http.js | 11 + devplacepy/static/js/ServiceMonitor.js | 27 +- devplacepy/static/js/StatisticsCharts.js | 20 +- devplacepy/static/js/StatisticsDashboard.js | 335 ++---------------- devplacepy/static/js/WorkspaceList.js | 106 ++++++ devplacepy/templates/CLAUDE.md | 4 + devplacepy/templates/_admin_backups_body.html | 111 ++++++ devplacepy/templates/_admin_cap_note.html | 1 + devplacepy/templates/_ai_usage_report.html | 181 ++++++++++ .../templates/_gateway_stats_fragment.html | 6 + .../templates/_gateway_stats_summary.html | 44 +++ devplacepy/templates/_service_metrics.html | 19 + devplacepy/templates/admin_audit_log.html | 2 +- devplacepy/templates/admin_backups.html | 10 +- devplacepy/templates/admin_base.html | 63 +--- devplacepy/templates/admin_communities.html | 3 +- devplacepy/templates/admin_devii_tasks.html | 8 +- devplacepy/templates/admin_game.html | 10 +- devplacepy/templates/admin_gateway.html | 84 +++-- .../templates/admin_issues_planning.html | 24 +- devplacepy/templates/admin_media.html | 2 +- devplacepy/templates/admin_moderation.html | 4 +- devplacepy/templates/admin_nodes.html | 2 + devplacepy/templates/admin_report.html | 4 +- devplacepy/templates/admin_settings.html | 58 +-- devplacepy/templates/admin_statistics.html | 113 ++++-- devplacepy/templates/admin_trash.html | 4 +- devplacepy/templates/admin_workspaces.html | 79 +++-- devplacepy/templates/ai_usage.html | 24 +- devplacepy/templates/base.html | 15 +- devplacepy/templates/containers_admin.html | 7 +- devplacepy/templates/containers_edit.html | 2 +- .../templates/docs/services-overview.html | 2 +- devplacepy/templates/service_detail.html | 24 +- devplacepy/templates/services.html | 7 +- devplacepy/templating.py | 2 + pyproject.toml | 2 +- tests/api/admin/aiusage/index.py | 31 ++ tests/api/admin/backups/pages.py | 54 +++ tests/api/admin/communities/index.py | 1 + tests/api/admin/containers/data.py | 34 ++ tests/api/admin/deviitasks.py | 23 ++ tests/api/admin/game.py | 33 ++ tests/api/admin/gateway/circuit.py | 251 +++++++++++++ tests/api/admin/gateway/stats.py | 51 +++ tests/api/admin/issues/planning_page.py | 33 ++ tests/api/admin/nodes/index.py | 2 + tests/api/admin/services/devii_tools.py | 2 +- tests/api/admin/services/pages.py | 65 ++++ tests/api/admin/statistics.py | 57 +++ tests/api/admin/workspaces/__init__.py | 0 tests/api/admin/workspaces/data.py | 102 ++++++ tests/e2e/admin/deviitasks.py | 25 +- tests/e2e/admin/issues/planning.py | 4 +- tests/e2e/profile/search.py | 2 +- tests/unit/admin_spec.py | 127 +++++++ 93 files changed, 2396 insertions(+), 1278 deletions(-) create mode 100644 devplacepy/admin_sections.py create mode 100644 devplacepy/routers/admin/CLAUDE.md create mode 100644 devplacepy/static/js/WorkspaceList.js create mode 100644 devplacepy/templates/_admin_backups_body.html create mode 100644 devplacepy/templates/_admin_cap_note.html create mode 100644 devplacepy/templates/_ai_usage_report.html create mode 100644 devplacepy/templates/_gateway_stats_fragment.html create mode 100644 devplacepy/templates/_gateway_stats_summary.html create mode 100644 devplacepy/templates/_service_metrics.html create mode 100644 tests/api/admin/backups/pages.py create mode 100644 tests/api/admin/game.py create mode 100644 tests/api/admin/gateway/circuit.py create mode 100644 tests/api/admin/issues/planning_page.py create mode 100644 tests/api/admin/services/pages.py create mode 100644 tests/api/admin/statistics.py create mode 100644 tests/api/admin/workspaces/__init__.py create mode 100644 tests/api/admin/workspaces/data.py create mode 100644 tests/unit/admin_spec.py diff --git a/devplacepy/admin_sections.py b/devplacepy/admin_sections.py new file mode 100644 index 00000000..126d91a1 --- /dev/null +++ b/devplacepy/admin_sections.py @@ -0,0 +1,38 @@ +# retoor + +from dataclasses import dataclass + + +@dataclass(frozen=True) +class AdminSection: + key: str + label: str + href: str + icon: str + + +ADMIN_SECTIONS: tuple[AdminSection, ...] = ( + AdminSection("users", "Users", "/admin/users", "\U0001f465"), + AdminSection("news", "News", "/admin/news", "\U0001f4f0"), + AdminSection("media", "Media", "/admin/media", "\U0001f5bc️"), + AdminSection("moderation", "Moderation", "/admin/moderation", "\U0001f6a9"), + AdminSection("trash", "Trash", "/admin/trash", "\U0001f5d1️"), + AdminSection("services", "Services", "/admin/services", "⚙️"), + AdminSection("gateway", "Gateway", "/admin/gateway", "\U0001f500"), + AdminSection("containers", "Containers", "/admin/containers", "\U0001f4e6"), + AdminSection("workspaces", "Workspaces", "/admin/workspaces", "\U0001f4bb"), + AdminSection("devii-tasks", "Devii tasks", "/admin/devii-tasks", "⏰"), + AdminSection("communities", "Communities", "/admin/communities", "\U0001f310"), + AdminSection("nodes", "Community nodes", "/admin/nodes", "\U0001f4e1"), + AdminSection("bots", "Bot Monitor", "/admin/bots", "\U0001f916"), + AdminSection("game", "Code Farm", "/admin/game", "\U0001f69c"), + AdminSection("ai-usage", "AI usage", "/admin/ai-usage", "\U0001f4ca"), + AdminSection("statistics", "Statistics", "/admin/statistics", "\U0001f4c8"), + AdminSection("audit-log", "Audit Log", "/admin/audit-log", "\U0001f4cb"), + AdminSection("backups", "Backups", "/admin/backups", "\U0001f4be"), + AdminSection("issues", "Ticket Planning", "/admin/issues/planning", "\U0001f5c2️"), + AdminSection("notifications", "Notifications", "/admin/notifications", "\U0001f514"), + AdminSection("settings", "Settings", "/admin/settings", "\U0001f527"), +) + +ADMIN_SECTION_KEYS: frozenset[str] = frozenset(section.key for section in ADMIN_SECTIONS) diff --git a/devplacepy/database/nodes.py b/devplacepy/database/nodes.py index c2ae1780..8b9c1a89 100644 --- a/devplacepy/database/nodes.py +++ b/devplacepy/database/nodes.py @@ -592,14 +592,23 @@ def raise_flag(kind: str, *, device_uid: str = "", user_uid: str = "", detail: s return table.find_one(uid=uid) -def list_flags(status: str = FLAG_OPEN) -> list[dict]: +def list_flags(status: str = FLAG_OPEN, limit: int | None = None) -> list[dict]: + window = {} if limit is None else {"_limit": limit} return list( get_table("node_flags").find( - status=status, deleted_at=None, order_by=["-created_at"] + status=status, deleted_at=None, order_by=["-created_at"], **window ) ) +def count_flags(status: str = FLAG_OPEN) -> int: + return get_table("node_flags").count(status=status, deleted_at=None) + + +def count_all_devices() -> int: + return get_table("node_devices").count(deleted_at=None) + + def resolve_flag(flag_uid: str, actor_uid: str) -> bool: return ( _execute( diff --git a/devplacepy/responses.py b/devplacepy/responses.py index 6037b455..809e68d6 100644 --- a/devplacepy/responses.py +++ b/devplacepy/responses.py @@ -19,7 +19,14 @@ def wants_json(request: Request) -> bool: return "application/json" in accept and "text/html" not in accept -def respond(request: Request, template: str, context: dict, *, model: type[BaseModel]): +def respond( + request: Request, + template: str, + context: dict, + *, + model: type[BaseModel], + status_code: int = 200, +): if wants_json(request): try: payload = model.model_validate(context).model_dump(mode="json") @@ -29,7 +36,9 @@ def respond(request: Request, template: str, context: dict, *, model: type[BaseM return JSONResponse(payload) from devplacepy.templating import templates - return templates.TemplateResponse(request, template, context) + return templates.TemplateResponse( + request, template, context, status_code=status_code + ) def action_result( diff --git a/devplacepy/routers/CLAUDE.md b/devplacepy/routers/CLAUDE.md index 5f2146c7..e2cb4a67 100644 --- a/devplacepy/routers/CLAUDE.md +++ b/devplacepy/routers/CLAUDE.md @@ -179,6 +179,10 @@ All dates displayed to users use European DD/MM/YYYY format. Implemented via: - **`time_ago()`** returns `DD/MM/YYYY` for items older than 30 days (instead of `"Xmo ago"`) - Services page has a JS `formatDate()` function for live polling updates +### Admin page specification + +Every admin route and template conforms to `devplacepy/routers/admin/CLAUDE.md` (A1-A11). Read it before adding or changing anything under `/admin`; it is enforced by `tests/unit/admin_spec.py`. + ### Admin pagination Both `/admin/users` and `/admin/news` use offset-based pagination via a reusable component: diff --git a/devplacepy/routers/admin/CLAUDE.md b/devplacepy/routers/admin/CLAUDE.md new file mode 100644 index 00000000..97c21b7e --- /dev/null +++ b/devplacepy/routers/admin/CLAUDE.md @@ -0,0 +1,82 @@ +# CLAUDE.md + +The specification every `/admin` page follows. Claude Code loads it whenever a file under `routers/admin/` is touched; the root, `routers/`, `templates/`, `static/js/` and `static/css/` `CLAUDE.md` files point here. A page that breaks a rule below is a defect, not a style choice. `tests/unit/admin_spec.py` enforces the mechanical rules (A1, A2, A5, A6, A7, A9, A10) against the real templates and routers, so a violation fails the suite. + +Code references: the section registry is `devplacepy/admin_sections.py`; the caps and floors are `ADMIN_LIST_CAP` and `ADMIN_POLL_FLOOR_SECONDS` in `routers/admin/_shared.py`; the cap note is `templates/_admin_cap_note.html`. + +## A1. Backend rendered, always + +A GET of an admin page returns the complete content in the HTML: every table, card, key figure, tab label and empty state is rendered by Jinja from data the handler computed. A placeholder such as "Loading..." in a template is forbidden. The page must be readable and correct with JavaScript off. + +JavaScript only enhances: live refresh, charts drawn on a ``, sorting, modals. The numbers and tables around a chart are server rendered; the chart is drawn from JSON embedded in the page. + +The only permitted live-first surface is a page whose whole purpose is a live channel (WebSocket) such as the Bot Monitor and the container terminal, and even those render their initial frame on the server. + +## A2. One handler, one builder, one model + +- The HTML route calls `respond(request, "