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 <noreply@anthropic.com>
8.2 KiB
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 <canvas>, 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, "<template>.html", ctx, model=XOut)withbase_seo_context(..., robots="noindex,nofollow")and a breadcrumb trailHome > Admin > <Page>. Nevertemplates.TemplateResponsedirectly: that drops the JSON face and the*Outschema. - The data the page shows is produced by ONE builder function. The HTML route and the refresh endpoint (
GET /admin/<page>/data,require_admin,JSONResponse) both call it. The two must never compute the same figures twice with different code. - Context keys never collide with a Jinja global (root rule:
viewer_is_admin, notis_admin). - Every admin page sets
"admin_section": "<key>"where the key exists inADMIN_SECTIONS.
A3. Page anatomy
Every page extends admin_base.html and, in this order, renders:
<div class="admin-toolbar">holding the page title as<h2>(never<h1>; the layout owns the document heading), thenadmin-countspans, filters and the primary action.- Optional
<nav class="admin-tabs" data-overflow-tabs>for page tabs. A tab is a real link (?tab=), rendered on the server. - The content:
admin-table-wrap > table.admin-table, or cards, or a formadmin-settings-form. - The empty state:
<p class="admin-empty">, neverempty-state, never an empty table. - Pagination via
_pagination.htmlwhen the list is paged (A6).
Tables carry <caption class="sr-only">, every <th> has scope="col", every icon-only or repeated row button has an aria-label. Page CSS goes in {% block extra_head %} after {{ super() }} (never re-link admin.css or sidebar.css; admin_base.html already loads them). No inline <style>, no style= attributes, no inline event handlers.
A4. Class vocabulary
Buttons are admin-btn with admin-btn-primary, admin-btn-danger, admin-btn-sm. Fields are admin-field, selects admin-select, forms admin-settings-form or admin-inline-form, hints admin-hint. Status chips reuse the page family badge (service-status, cm-badge, workspace-badge). The public-site classes btn, btn-primary, btn-danger, hint-text, empty-state, admin-header are forbidden in admin templates. A missing admin class is added to admin.css, never worked around with a public class. Destructive buttons carry data-confirm (and data-confirm-danger for role/quota style changes).
A5. Time
Every instant shown to a viewer is local_dt(iso, mode) or dt_ago(iso); never format_date/time_ago for an instant (those stay for JSON and non-timestamp date fields). When client JS re-renders a row it emits the same <time data-dt="..."> markup, and LocalTime localizes it through its MutationObserver; JS never formats an instant itself with toLocaleString/toLocaleTimeString.
A6. Everything is capped
No list is unbounded.
- A list that can grow with users or content is paginated:
build_pagination(page, total)plus_limit/_offsetin the query and_pagination.html. Sorting is in SQL (order_by), neverrows.sort()over the whole table. - A list that is naturally small (services, gateway providers) still reads with
_limit=ADMIN_LIST_CAPand renders_admin_cap_note.html(_shown,_total) so truncation is visible, never silent. - Per-row work (queries,
awaits, service calls) is done for the visible page only, in batch (get_users_by_uidsand friends), never per row of the whole table. - Query parameters that size a computation (
hours,top_n,limit) are clamped on the server to a declared constant.
A7. Heavy and remote work
A GET handler must not wait on a remote service. Gitea, providers and any network call go through a cache with a fixed TTL and a hard item cap; the handler renders the cached value at once and keeps the page's explicit error state (*_error) when the source is down. A computation costing more than one page of plain queries (statistics, usage analytics) is computed once per request: the HTML route embeds its result, and a tab or window change either navigates (server render) or fetches /data, never both.
A8. Live refresh
- The shared
Polleronly:new Poller(fn, ms, { pauseHidden: true, immediate: false }).immediate: falsebecause the first paint is already on the page (A1). RawsetIntervalis forbidden. - Interval floor is
ADMIN_POLL_FLOOR_SECONDS(15 s); a page that needs faster is a live channel. - Fetch through
Http.getJson; never a barefetch. - The refresh response is the
/dataJSON of A2, or, for a page made of server-rendered sections, HTML fetched withHttp.getHtml(the page itself, or a/fragmentroute returning the same partial) and swapped into the[data-live]regions (Backups, Community pages, AI usage, Gateway stats). The markup then lives only in Jinja and the one builder feeds the page, the fragment and/data. The client re-renders only the regions that changed and preserves open modals, focus, scroll position and input values. - Initial data for charts is embedded as
<script type="application/json" id="<root>-initial">{{ initial | tojson }}</script>and read synchronously; the client does not issue a second request to learn what the server already knew.
A9. Assets
- One copy of each vendored library. Chart.js is
/static/vendor/chartjs/chart.umd.min.js, loaded withdeferthroughstatic_url(...)from{% block extra_js %}only on pages that draw charts. - Page JS is one ES6 module per class in
static/js/, started from a three-line module block inextra_js. No page logic inline.
A10. Navigation is one registry
The admin sections are declared once in devplacepy/admin_sections.py (ADMIN_SECTIONS, exposed as the admin_sections Jinja global). admin_base.html (desktop sidebar) and the admin block of base.html (the phone menu, because the sidebar is hidden at 1024 px and below) both loop over it. A new admin page adds one registry entry and nothing else; hand-writing a nav link in either template is forbidden. Every admin_section value passed by a route must exist in the registry.
A11. Responsive
Everything works at 360 px. Tables sit in admin-table-wrap (horizontal scroll inside the wrap, never the page). A toolbar with more than three controls wraps; a button group of more than three becomes a <select> or a dp-action-menu. Touch targets are at least 44 px (admin.css already enforces it for admin-btn/admin-select).
Checklist for a new or changed admin page
- Registry entry in
ADMIN_SECTIONS,admin_sectionmatches. - Builder function,
respond(... model=XOut),/dataendpoint if it refreshes, audit event for every mutation. - Template follows A3, A4, A5; no placeholder text; caps and pagination per A6.
- JS (only if needed) per A8 and A9.
tests/api/admin/...asserts the first response already contains the data (not "Loading"), andtests/unit/admin_spec.pystill passes.