Slim root CLAUDE.md to global-only rules, move subsystem detail to nested files

This commit is contained in:
2026-11-08 20:33:09 +01:00
parent 078d0657ff
commit 33eb090e27
12 changed files with 107 additions and 171 deletions
+25 -164
View File
@@ -2,7 +2,10 @@
This file provides guidance to Claude Code when working with code in this repository. It holds only what applies regardless of which part of the codebase is being touched. Deep, subsystem-specific detail lives in nested `CLAUDE.md` files placed inside the relevant directory - Claude Code auto-loads a nested file only when a file under that directory is read or edited, so the always-loaded cost of this repository stays proportional to this file alone. See "Subsystem map" below for the full list.
It is a big project, whatever you are implementing, it is probably done before. You should look it up and match the implementation structurely and visually. For inconsistency there is zero tolerance policy. Develop dry, kiss, re-usable code, consistent with existing implementation. Literally always try to find relatable examples before making a modification. If no-example exists, explain to user what is the case and let user decide what to do and how to continue.
It is a big project, whatever you are implementing, it is probably done before. You should look it up and match the implementation structurely and visually. For inconsistency there is zero tolerance policy. Develop dry, kiss, re-usable code, consistent with existing implementation. Literally always try to find relatable examples before making a modification. If no-example exists, explain to user what is the case and let user decide what to do and how to continue.
The completion contract for every change is [DEFINITION_OF_DONE.md](./DEFINITION_OF_DONE.md): universal gates, test obligations, the four-layer rigor procedure for spendable resources and races, per-subsystem rules, and the final checklist. A change is done only when every applicable gate in it passes.
## Project
@@ -14,7 +17,7 @@ DevPlace is a server-rendered social network for developers. FastAPI backend ser
- **Templates:** `devplacepy/templates/`. Shared `templates` instance from `devplacepy.templating` - all routers import from there, never instantiate their own.
- **Ports:** 10500 (dev), 10501 (tests; the serial suite uses a single uvicorn subprocess).
- **Username:** letters, numbers, hyphens, underscores only, 3-32 chars. **Password:** minimum 6 chars.
- **Avatars:** Multiavatar SVG generated locally from a seed in <5ms, in-memory cache cleared on restart, fallback to initial-based SVG on error. URL `/avatar/multiavatar/{seed}?size={size}`. The seed is per-user: the nullable `users.avatar_seed` column overrides the username. Always resolve it through the single null-safe choke point `avatar.avatar_seed(user)` (a Jinja global) - `user.get("avatar_seed") or user.get("username")` - never read `avatar_seed` or pass `username` to `avatar_url(...)` directly; every render site (the `_avatar_link.html` partial, `og_image`, the devRant avatar payload, etc.) goes through it. Regenerate is owner-or-admin at `POST /profile/{username}/regenerate-avatar` (writes a fresh `generate_uid()`, invalidates the user cache, audits `profile.avatar.regenerate`); the old seed is never stored, so the old avatar cannot return. Devii tool `regenerate_avatar` (`CONFIRM_REQUIRED`).
- **Avatars:** Multiavatar SVG generated locally at `/avatar/multiavatar/{seed}?size={size}`. Seed resolution, regenerate flow, and the owner-or-admin rule live in `devplacepy/templates/CLAUDE.md` ("Avatar seed choke point").
## Commands
@@ -55,60 +58,12 @@ devplace token list <username> # list a user's active access tokens
devplace token revoke <token_uid> # revoke a single access token by uid
devplace token revoke-all <username> # revoke all access tokens for a user
devplace token prune # soft-delete all expired access tokens
devplace news clear # delete all news rows
devplace news sanitize # strip HTML from news descriptions/content
devplace attachments prune # remove orphan attachment records/files
devplace system prune [--dry-run] # safe but aggressive: purges soft-deleted attachment/project-file blobs, sweeps blob files with zero DB reference at all (e.g. left by an interrupted/racing sync), and GCs orphaned container workspace dirs
devplace devii reset-quota <username> # reset one user's rolling 24h AI quota
devplace devii reset-quota --guests # reset every guest quota
devplace devii reset-quota --all # reset every quota (users and guests)
devplace devii tasks list [--all] # list scheduled Devii tasks and their owners
devplace devii tasks disable <uid> # disable one scheduled task
devplace devii tasks prune # disable every task whose owner may not schedule
devplace gateway quota list # list AI gateway quota rules and current 24h spend
devplace gateway quota set --limit-usd N [--owner-kind K] [--owner-id ID] [--app-reference APP] [--label L] [--uid UID]
devplace gateway quota delete <uid> # delete a quota rule
devplace gateway quota reset [--owner-kind K] [--owner-id ID] [--app-reference APP] # clear the counted 24h spend (keeps the usage history)
devplace zips prune # delete expired zip archives + job rows
devplace zips clear # delete every zip archive + job row
devplace forks prune # delete expired completed fork job rows (forked projects persist)
devplace forks clear # delete every fork job row (forked projects persist)
devplace community discover <query> [--run] [--relearn] [--dry-run] # discover, learn and generate collectors for an external community
devplace community run <slug> [--dry-run] # run a community's collectors through the sync API
devplace community login <slug> [--login-user U] [--login-email E] [--login-password P | --clear] # store or remove the account used to log in
devplace community list # list communities
devplace messaging prune-tickets # delete expired WebSocket auth tickets (ws_tickets)
devplace seo prune # delete expired SEO audit reports + job rows
devplace seo clear # delete every SEO audit report + job row
devplace seo-meta prune # delete expired SEO metadata job rows (generated metadata persists)
devplace seo-meta clear # delete every SEO metadata job row (generated metadata persists)
devplace deepsearch prune # delete expired DeepSearch sessions + job rows + collections
devplace deepsearch clear # delete every DeepSearch session + job row + collection
devplace isslop analyze <url> # run a AI usage analysis from the terminal (report persists)
devplace isslop prune # delete expired AI usage analysis job rows (analyses + reports persist)
devplace isslop clear # delete every AI usage analysis, its report and job rows
devplace quiz prune # delete abandoned/expired quiz attempts older than the retention window
devplace game market prune # delete Code Farm market tick buckets older than the tracking window
devplace game steals prune # delete Code Farm raid records older than the raid-efficiency window
devplace game era status # show the current Code Farm Era
devplace game era start <name> [--days N] # start a Code Farm Era (default 28 days)
devplace game era end # end the running Code Farm Era (ranks, awards Stars, records results)
devplace accounts pending # list deleted accounts awaiting their purge
devplace accounts prune # permanently purge accounts past the deletion grace window (--dry-run to preview)
devplace backups list # list recorded backups
devplace backups run <database|uploads|keys|full> # enqueue a backup (processed by the running server)
devplace backups prune # remove backup records whose archive file is missing
devplace backups clear # delete every backup archive + record
devplace containers list # list container instances
devplace containers reconcile # run one reconcile pass (desired vs docker ps)
devplace containers prune # reap orphan containers + dangling images
devplace containers prune-builds # remove legacy per-project images + clear dockerfiles/builds tables (one-time)
devplace containers gc-workspaces # remove workspace dirs with no instances
devplace emoji-sync # regenerate static/js/emoji-shortcodes.js from the emoji library (run after an emoji dep bump)
devplace embeds-sync # regenerate static/js/embed-spec.js from devplacepy/embeds.py (run after editing the embed table)
devplace migrate-data # relocate legacy runtime files into data/ (idempotent; --dry-run to preview)
```
Per-subsystem commands live in the nested file: `devplace devii ...` (Devii), `devplace gateway quota ...` (AI gateway), `devplace backups ...` (backup service), `devplace containers ...` (container manager), `devplace news ...` (news service), `devplace community ...` (community discovery), `devplace messaging prune-tickets` (messaging), `devplace {zips|forks|seo|seo-meta|deepsearch|isslop} ...` (async jobs), `devplace quiz prune` (quizzes), `devplace game ...` (Code Farm), `devplace accounts ...` (moderation), `devplace apikey backfill`, `devplace attachments prune`, `devplace system prune` (database), `devplace emoji-sync` (frontend JS), `devplace embeds-sync` (templates).devplace migrate-data # relocate legacy runtime files into data/ (idempotent; --dry-run to preview)
```
### Runtime data layout (single source of truth)
Every runtime/user-generated artifact lives under one root, `config.DATA_DIR` (`DEVPLACE_DATA_DIR`, default `<repo>/data`). `config.py` derives every runtime path from it and lists them in the `DATA_PATHS` registry; `ensure_data_dirs()` creates the whole tree before anything is written. **No module computes a runtime path from scratch** - import the constants (`UPLOADS_DIR`, `ATTACHMENTS_DIR`, `PROJECT_FILES_DIR`, `ZIPS_DIR`, `ZIP_STAGING_DIR`, `FORK_STAGING_DIR`, `KEYS_DIR`, `BOT_DIR`, `LOCKS_DIR`, `CONTAINER_WORKSPACES_DIR`, `DEVII_TASKS_DB`, `DEVII_LESSONS_DB`, `VAPID_*_FILE`, `SERVICE_LOCK_FILE`, `INIT_LOCK_FILE`). Uploads are physically under `data/uploads/` but still served at the unchanged `/static/uploads/` URL. Stored DB values for attachments/project files are relative (`directory` + `stored_name`), so no DB rewrite is ever needed for a layout change.
@@ -191,63 +146,15 @@ The AI usage analyzer (`devplace isslop analyze`, the `/tools/isslop` job servic
### Routing layout
Routers in `devplacepy/routers/` are organised as a **directory tree that mirrors the endpoint (URL) path**, exactly like `tests/`. A domain with a single resource stays one flat file (`feed.py`, `posts.py`, ...); a domain with several sub-resources is a **package directory** split one file per sub-resource. Each leaf declares its own `router = APIRouter()`; the package `__init__.py` aggregates with `router.include_router(...)`. A leaf owning the domain's collection-root (`""`) route must be the package's base router (FastAPI rejects an empty path under an empty prefix). Full elaboration, per-domain detail, and the complete deep-dive live in `devplacepy/routers/CLAUDE.md` - read it before touching routing. Compact map:
| Prefix | Router |
|--------|--------|
| `/auth` | auth/ package |
| `/feed`, `/posts`, `/comments` | flat files |
| `/topics` | topics.py - crawlable per-topic category index pages (`/topics` hub, `/topics/{topic}` listing) |
| `/projects`, `/projects/{slug}/files`, `/projects/{slug}/containers` | projects/ package - see `routers/projects/CLAUDE.md` |
| `/profile` | profile/ package (customization, notifications, ai-correction, ai-modifier, interactions, telegram, usage) |
| `/messages` | messages.py - see `services/messaging/CLAUDE.md` |
| `/notifications`, `/votes`, `/reactions`, `/bookmarks`, `/polls`, `/avatar`, `/follow`, `/leaderboard` | flat files |
| (none) | relations.py - block/mute |
| `/` | landing.py - home route (guests get the splash, users the dashboard) |
| `/admin`, `/admin/services`, `/admin/containers` | admin/ package |
| `/issues` | issues/ package - see `services/gitea/CLAUDE.md` |
| `/gists`, `/news`, `/uploads`, `/media` | flat files |
| `/giphy` | giphy.py - GIF picker backend (search, trending, attach), see `services/giphy/CLAUDE.md` |
| `/openai` | openai_gateway.py - see `services/openai_gateway/CLAUDE.md` |
| `/devii` | devii.py - see `services/devii/CLAUDE.md` |
| `/zips`, `/forks` | see `services/jobs/CLAUDE.md` |
| `/tools` | tools/ package (SEO diagnostics, DeepSearch, AI Usage Analyzer) - see `services/jobs/CLAUDE.md` |
| `/p/{slug}` | proxy.py - container ingress reverse proxy |
| `/xmlrpc` | xmlrpc.py - see `services/xmlrpc/CLAUDE.md` |
| `/api` | devrant/ package - see `routers/devrant/CLAUDE.md` |
| `/dbapi` | dbapi/ package, **primary-administrator-only, strictly READ-ONLY** - see `services/dbapi/CLAUDE.md` |
| `/sync` | sync/ package, **administrator only**, off by default - see `services/sync/CLAUDE.md` |
| `/game` | game/ package - see `services/game/CLAUDE.md` |
| `/reports`, `/admin/moderation`, `/workspaces` | reports.py, admin/moderation.py, workspaces.py - see `services/moderation/CLAUDE.md` |
| `/quizzes` | quizzes/ package - see `services/quiz/CLAUDE.md` |
| `/battles` | battles.py - see `services/opinionwar/CLAUDE.md` |
| (none) | push.py (web push/PWA), docs.py (see `routers/docs/CLAUDE.md`) |
| `/pubsub` | pubsub.py - see `services/pubsub/CLAUDE.md` |
| (none) | seo.py - `/robots.txt`, `/sitemap.xml` |
Routers in `devplacepy/routers/` are organised as a **directory tree that mirrors the endpoint (URL) path**, exactly like `tests/` (one segment per directory, last segment is the file; packages aggregate with `include_router`). A leaf owning the domain's collection-root (`""`) route must be the package's base router. Full URL prefix map, aggregation rules, HTML/JSON negotiation, FastAPI patterns, and per-domain detail live in `devplacepy/routers/CLAUDE.md` - read it before touching routing. Sub-domain pages: `routers/projects/`, `routers/docs/`, `routers/devrant/` (each with its own nested file, see Subsystem map).
### Templates and frontend
- All routers MUST import the shared `templates` from `devplacepy.templating`. Do NOT instantiate `Jinja2Templates` per router.
- Templates extend `base.html`; page CSS via `{% block extra_head %}`, page JS via `{% block extra_js %}`.
- **Nav active state is the `nav_active` Jinja global**, never an inline path check.
- **Static asset URLs are boot-versioned:** never hardcode a bare `/static/...` href/src - use `static_url(path)` (Jinja) / `assetUrl(path)` (JS).
- All JS is ES6 modules, one class per file, instantiated as `app`. Custom web components (`dp-*` prefix) and shared frontend utilities (`Http`, `Poller`, `JobPoller`, `OptimisticAction`, `FloatingWindow`, `ScrollMemory`) are documented in `devplacepy/static/js/CLAUDE.md` - reuse them, never re-implement.
- CDN scripts in `base.html` MUST use `defer` or `type="module"`.
- Modal system, shared template partials (`_avatar_link.html`, `_user_link.html`, `_sidebar_search.html`) are documented in `devplacepy/templates/CLAUDE.md`.
All routers import the shared `templates` from `devplacepy.templating` (never instantiate per router); templates extend `base.html` (`extra_head`/`extra_js` blocks, `nav_active` global, boot-versioned `static_url`/`assetUrl`, deferred CDN scripts). JS is ES6 modules, one class per file, `dp-*` web components plus shared utilities (see `devplacepy/static/js/CLAUDE.md`). Modal system and shared partials: see `devplacepy/templates/CLAUDE.md`.
### Content rendering pipeline
**Server-rendered content and titles are rendered on the BACKEND for SEO** (`devplacepy/rendering.py`, Jinja globals `render_content(text)`/`render_title(text)`). This is the default for all content that exists at request time (post bodies, comments, news, project/gist descriptions, DM history, every content title). It mirrors the client pipeline using **mistune**: em-dash normalization, emoji shortcodes, GFM markdown (`escape=True` - the server XSS control), then a media pass turning bare URLs into embeds and `@mentions` into links. Both are `@lru_cache`d. Server-rendered code blocks get syntax highlighting + Copy button client-side via `ContentEnhancer`.
The CLIENT pipeline (`ContentRenderer.js`, `dp-content`/`dp-title`) is retained ONLY for genuinely live/dynamic content that does not exist at request time (live comments, DM bubbles, Devii/DeepSearch/Docs chat, planning report). Runs `marked` -> **`DOMPurify.sanitize`** (the client XSS control, fail-closed) -> highlight.js -> media/autolink. **Do NOT add `data-render` to server-rendered content - call `render_content`/`render_title` instead.**
**Emoji shortcodes are the full GitHub/Discord `:name:` set** (~4869 names), generated once from the `emoji` library by `rendering.py` `build_emoji_shortcodes()`; the frontend gets the identical map via the generated `static/js/emoji-shortcodes.js` (regenerate with `devplace emoji-sync` after bumping the dependency, never hand-edit).
**YouTube and YouTube Music embeds** have ONE specification, `devplacepy/embeds.py` (`EmbedParser.parse(url)` -> `Embed(kind, video_id, list_id, start, music)`, `EmbedParser.src(embed)`): exact host allowlists (never substring matching), query-order independent parsing, validated ids only (`[A-Za-z0-9_-]{11}` video, `{13,64}` list) so nothing but validated characters can reach an iframe `src`. YouTube Music has no player of its own and `music.youtube.com` sends `X-Frame-Options: SAMEORIGIN`, so a music link is YouTube's player (`www.youtube.com/embed/...`) wrapped in `<div class="embed-music">` with an "Open in YouTube Music" caption link; playlists/albums use `embed/videoseries?list=`. `/browse`, `/channel`, `/search`, `/library` carry no embeddable id and stay plain links. At most `MAX_MUSIC_EMBEDS` (3) music embeds render per content item, the overflow stays a plain link; plain YouTube is uncapped. `rendering.py` (`_youtube_embed`, per-`_MediaProcessor` `_EmbedBudget`) and `ContentRenderer.js` (`youtubeEmbed`, via `static/js/EmbedParser.js`) both follow it; the JS constants come from the generated `static/js/embed-spec.js` (`devplace embeds-sync`, never hand-edit). Never add another YouTube regex.
**Email anonymization:** both `_render_content` and `_render_title` mask email addresses to prevent doxing. `_mask_emails` in `rendering.py` runs on rendered text nodes only (inside `_transform_text`, `_MediaProcessor`, and `_InlineFilter` - never before mistune, or the `*` mask characters would be parsed as emphasis) and stars ~80% of the local part (keeps a leading 20%, minimum one visible char). Addresses on `molodetz.nl` (and its subdomains) are exempt and render verbatim.
**Em-dash normalization:** `_normalize_dashes` in `rendering.py` replaces all forms (em dash `\u2014`, en dash `\u2013`, and their HTML entities) with a hyphen BEFORE mistune processes the text. Runs inside `_render_content`/`_render_title` which are `@lru_cache`d, so each unique text is normalized once. No per-template overhead.
Server content renders on the backend for SEO (`render_content`/`render_title` in `devplacepy/rendering.py`); the client pipeline is only for live content (`DOMPurify` fail-closed). Full pipeline rules (emoji map, YouTube spec, email masking, dash normalization) live in `devplacepy/templates/CLAUDE.md` ("Content rendering pipeline").
### Auth
@@ -255,11 +162,7 @@ Session cookies named `session`, value a 64-char hex token. Passwords hashed wit
### Database
SQLite via `dataset.connect` with WAL + 30s busy timeout + 256MB mmap. **SQLite is synchronous by design and will never be made async (hard rule).** The `dataset`/SQLite layer is called directly inside async route handlers - the database is a local file tuned with WAL/`synchronous=NORMAL`/8MB page cache/256MB mmap, so queries are sub-millisecond and never meaningfully stall the event loop. Do NOT convert the database layer to async, wrap calls in a threadpool/`run_in_executor`/`to_thread`, or raise synchronous DB access as a blocking-I/O concern - this is a settled design decision, not open for revisiting.
`init_db()` is idempotent and **ensures the full column set of any table code filters on** before creating indexes - `dataset` gives a lazily-created table only the columns of its first insert, so a partial insert elsewhere would leave a reduced schema that later 500s with `no such column`. Full dataset rules, indexing conventions (the soft-delete planner trap), site settings, and the complete table list live in `devplacepy/database/CLAUDE.md`.
Runtime config lives in `site_settings`, read via `get_setting(key, default)`/`get_int_setting(key, default)` (60s TTL cache, cross-worker invalidated via `cache_state`). Batch helpers (`get_users_by_uids`, `get_comment_counts_by_post_uids`, `get_vote_counts`, `load_comments`) exist specifically to avoid N+1 - use them instead of per-row lookups.
**SQLite is synchronous by design and will never be made async (hard rule).** The `dataset`/SQLite layer is called directly inside async route handlers; never wrap it in a threadpool/`run_in_executor`/`to_thread` or raise sync DB access as a blocking-I/O concern. Dataset rules, indexing, soft delete, visibility spec, `site_settings`, batch helpers (use instead of N+1), and the table list live in `devplacepy/database/CLAUDE.md`.
### Per-user site customization (CSS/JS)
@@ -274,19 +177,19 @@ Users and guests inject their own CSS and JS, scoped to a page type or globally,
### Background task queue, AI correction/modifier, background services
`services/background.py` `background.submit(fn, *args)` is a generic fire-and-forget offload onto one per-worker `asyncio.Queue`; when the consumer isn't running (tests, full queue) it runs the callable **inline**, so audit/notification/XP writes stay deterministic for the suite while production defers them. It is the choke point for every audit-log write, every XP award, and every notification - handlers call `award_rewards`/`create_notification` directly (never wrap them in `background.submit`, that double-queues). AI content correction (opt-in, off by default) and the AI modifier (`@ai <instruction>` inline directive, on by default) rewrite user prose via the internal gateway; sync apply mode never blocks the event loop (`run_in_executor` + the `await_pending_corrections` middleware). `BaseService`/`ServiceManager` provide the async run loop and singleton registry for background services (`NewsService`, `GatewayService`, `DeviiService`, `BotsService`, container/audit/telegram reconcilers). Full detail on all of this, plus presence and the live view relay, is in `devplacepy/services/CLAUDE.md`.
`background.submit` offload, AI correction/modifier via the internal gateway, `BaseService`/`ServiceManager`, presence, and the live view relay: see `devplacepy/services/CLAUDE.md`.
### Container manager, Devii assistant, AI gateway, async jobs, audit log
DevPlace ships a Docker-backed **Container manager** (admin-only, one shared `ppy:latest` image, security-hardened rootless workflow via a `sudo` superclone and `aptroot`), the **Devii** in-platform agentic assistant (WebSocket terminal, per-owner-channel sessions, scheduler/reminders, self-learning lessons, user-defined virtual tools, self-configured behavior, browser-automation client tools), the **AI gateway** (`/openai/v1/*`, single point of truth for every AI call, per-user cost attribution, provider/model routing overlay), **async job services** (`JobService` base pattern: zip, fork, SEO diagnostics, SEO metadata generation, DeepSearch, AI Usage Analyzer), and an admin-only append-only **audit log** (`record`/`record_system` entrypoints, `events.md` catalogue of every recorded event key, never raises into the caller). These are among the largest subsystems in the codebase - read their dedicated nested `CLAUDE.md` files (see Subsystem map) before working in any of them; do not assume prior knowledge from this summary.
Container manager, Devii, AI gateway, async jobs, audit log: see their nested `CLAUDE.md` files (Subsystem map). Read the dedicated file before working in any of them.
### Telegram bot, email, devRant compatibility API, issue tracker
Devii is also reachable over **Telegram** (one supervised long-poller subprocess, `channel="telegram"` isolated conversation thread), can drive a user's own **external mailbox** over IMAP/SMTP (stdlib only, credentials in a soft-deletable table, SSRF-guarded), and DevPlace exposes a **devRant-compatible REST API** at `/api` (translates devRant requests onto native posts/comments/votes via reused audited cores, ID mapping is `posts.id`/`comments.id` directly). The **issue tracker** at `/issues` has no local store - it reads/writes Gitea live via one shared bot token, filing is an async AI-enhanced job. Full detail in the respective nested `CLAUDE.md` files.
Telegram bridge, email tools, devRant API, Gitea issue tracker: see their nested `CLAUDE.md` files (Subsystem map).
### SEO
`devplacepy/seo.py` generates JSON-LD schemas (WebSite, BreadcrumbList, DiscussionForumPosting, ProfilePage, SoftwareApplication). Every router builds context via `base_seo_context(request, ...)`. Auth/messages/notifications are `noindex,nofollow`; profiles with fewer than 2 posts are `noindex,follow`. `/robots.txt` and `/sitemap.xml` are served by `routers/seo.py`. Full implementation map (template layer, heading hierarchy, slugs, related posts, performance, default OG image, SEO tests) is in `devplacepy/routers/CLAUDE.md`.
JSON-LD schemas via `devplacepy/seo.py` and `base_seo_context`; index/follow rules per surface. Full implementation map in `devplacepy/routers/CLAUDE.md`.
## The production database is never touched without explicit confirmation (hard rule)
@@ -311,79 +214,37 @@ The escape hatch is deliberately two-factor and must never be self-served: after
- **Roles are stored capitalized:** `users.role` is exactly `"Admin"` or `"Member"`. Always test admin-ness through the `is_admin(user)` global (case-sensitive `== "Admin"`) - never hand-roll a lowercase compare. **Any write to `users.role` MUST call `database.invalidate_admins_cache()`.**
- **Admin seniority: a junior admin cannot manage a more senior admin.** Every per-user mutation in `routers/admin/users.py` and `routers/admin/moderation.py` is gated by `is_senior_admin(actor, target)` (`routers/admin/_shared.py`) - blocks (audits `result="denied"`) when the target is an Admin who registered earlier. Server-side, so it also covers Devii's admin tools.
- **Never pass a `respond()` context key that collides with a Jinja global.** `respond(request, template, ctx, model=XOut)` feeds the same `ctx` to both the Pydantic model (JSON) and the template. A key like `is_admin`/`avatar_url`/`is_self` holding a non-callable value shadows the global across the whole inheritance chain, turning `{% if is_admin(user) %}` into `False(user)` -> `TypeError`, a 500 that fires only for the branch that calls the global. Name viewer/permission flags distinctly (`viewer_is_admin`, not `is_admin`) in both schema and context.
- **Project visibility (`is_private`) and read-only (`read_only`)** are owner-controlled flags on `projects`. Read access is gated by the single `content.can_view_project(project, user)` predicate at EVERY read surface - never re-implement the check inline. Predicate: `not is_private OR is_owner OR (is_admin AND owner is not an admin)` - a project hidden by a member stays visible to any admin, but one hidden by an admin is visible only to that owner admin. **Containers have their own, stricter isolation predicates** (`owns_instance`, `can_view_project_containers`, `can_view_instance`, `can_manage_instance`) - the primary administrator sees/manages every container; any other admin can VIEW others' containers only on public projects and can MANAGE only instances they own. Read-only is enforced as a single data-layer guard `project_files._guard_writable(project_uid)` at the top of every mutation entrypoint - add it to any NEW file-mutating function. Devii may flip read-only/visibility only after explicit confirmation (`CONFIRM_REQUIRED`). Full UI-level detail in `devplacepy/routers/projects/CLAUDE.md`.
- **Content visibility (`published`/`hidden`/`draft`/`offline`) on posts, gists, projects and news is one specification, `devplacepy/database/visibility.py`.** Any new read of those tables applies `listed_clause`/`listed_sql` (or goes through `paginate`, which does it), and any single-item or target access uses `content.can_view_item`/`can_view_target`. NULL reads as published. Full detail in `devplacepy/database/CLAUDE.md`.
- **Project visibility and read-only** are owner-controlled flags gated by single predicates (`can_view_project`, container isolation predicates, `_guard_writable`): see `devplacepy/routers/projects/CLAUDE.md`.
- **Content visibility on posts, gists, projects and news is one specification** (`database/visibility.py`, choke points `listed_clause`/`listed_sql`, `can_view_item`/`can_view_target`): see `devplacepy/database/CLAUDE.md`.
- **Deletions ALWAYS require confirmation:** `confirmation_error` gates EVERY content delete tool via `CONFIRM_REQUIRED` (`delete_post`, `delete_comment`, `delete_gist`, `delete_project`, `project_delete_file`, `delete_media`, `delete_attachment`, `admin_delete_news`, container delete, and any `container_exec` matching `dispatcher.DESTRUCTIVE_COMMAND`). The first call is refused; the agent must show the exact target then pass `confirm=true`. **Load-bearing: every confirmation-gated tool MUST also declare a `confirm` boolean param in its catalog spec** - schemas set `additionalProperties: false`, so a gated tool without a declared `confirm` param can never receive it and loops forever.
## Every user-generated surface is reportable by construction (hard rule)
A new content table added to `SOFT_DELETE_TABLES` that is visible to anyone other than its author MUST be registered in `database/moderation.py` `REPORTABLE_TARGETS`, MUST resolve in `resolve_object_url`, and MUST include `_report_button.html` in its action bar. A table that is genuinely private to its owner goes in `UNREPORTABLE_TABLES` **with its reason** instead. `tests/unit/database/moderation.py` computes the difference and fails the suite on anything unclassified, so report coverage is closed under future additions rather than remembered; the e2e coverage test enforces the third requirement.
The same rule keeps the untriggered app-store conditionals untriggered: **no social login, no payment path, no purchasable randomness, no advertising, and no cross-app tracking** may be introduced without also implementing the obligations each of them creates (Sign in with Apple, in-app purchase, odds disclosure, ad reporting, App Tracking Transparency). Full detail in `devplacepy/services/moderation/CLAUDE.md`.
New user-generated tables are classified in `REPORTABLE_TARGETS` (with `resolve_object_url` and `_report_button.html`) or in `UNREPORTABLE_TABLES` with a reason; the suite enforces it. No social login, payment, purchasable randomness, advertising, or cross-app tracking without their app-store obligations. Full detail in `devplacepy/services/moderation/CLAUDE.md`.
## Modal pattern
`Application.js` `initModals()` toggles a `.visible` CSS class on `.modal-overlay`; the CSS rule `.modal-overlay.visible { display: flex; }` handles visibility. Triggers usually have `href="#"`, so call `e.preventDefault()`. `.modal-close` is wired generically - no inline JS needed. Full modal/partial/CDN detail in `devplacepy/templates/CLAUDE.md`.
See `devplacepy/templates/CLAUDE.md` (modal system, partials, CDN).
## Polymorphic comments and votes
The `comments` table uses `(target_type, target_uid)` so `_comment_section.html` works for `post`, `project`, `gist`, and `news`. Votes follow the same shape via `/votes/{target_type}/{uid}`. `resolve_target_redirect()` in `comments.py` maps target_type back to the correct detail URL. Full detail (reactions/bookmarks/polls/heatmap/follow/block-mute reuse the same target-type pattern) in `devplacepy/routers/CLAUDE.md`.
`(target_type, target_uid)` shapes comments, votes, and the engagement reuse family: see `devplacepy/routers/CLAUDE.md`.
## Project-wide soft delete (hard rule)
**Every removal is a soft delete; only garbage collection is a hard delete.** Removable rows carry `deleted_at` (ISO timestamp) + `deleted_by` (actor uid or `system`); a live row has `deleted_at = NULL` and every list/count read filters `deleted_at IS NULL`. The table set is `database.SOFT_DELETE_TABLES`; `init_db` ensures both columns + a partial index per table. Core primitives in `database/`: `soft_delete`, `soft_delete_in`, `restore`, `purge`, `list_deleted`/`count_deleted`, `restore_event`/`purge_event`.
- **Every INSERT into a soft-deletable table MUST write `deleted_at: None, deleted_by: None`** - `dataset.find(deleted_at=None)` on a table missing the column matches NOTHING, silently hiding all rows on a fresh DB.
- **Any new read of a soft-deletable table MUST filter `deleted_at IS NULL`.**
- **Toggles revive, never duplicate:** look up the physical row ignoring `deleted_at`, stamp on toggle-off, clear on re-toggle.
- **Cascades share one `stamp`** so the event restores/purges atomically.
- **Delete authz is owner-OR-admin on the endpoint** - one check covers the UI and Devii.
- **GC stays HARD** (job sweep, metrics ring, usage-ledger prune/reset, expired-session cleanup, fork rollback). Logout is soft (auditable); only expiry GC is hard.
Admin **Trash** at `/admin/trash` restores/purges by event. Full table list, dataset rules, indexing conventions (the soft-delete planner trap), and site settings are in `devplacepy/database/CLAUDE.md`.
**Every removal is a soft delete; only garbage collection is a hard delete.** Inserts write `deleted_at: None, deleted_by: None`; reads filter `deleted_at IS NULL`; toggles revive; cascades share one stamp; delete authz is owner-OR-admin. Full table list, primitives, and indexing rules in `devplacepy/database/CLAUDE.md`.
## Testing
Playwright (NOT pytest-playwright). Around 2882 tests in `tests/`, split into three category directories by *what they exercise*: `tests/api/` (HTTP integration, no browser), `tests/e2e/` (Playwright browser), `tests/unit/` (pure in-process). **The directory tree mirrors the path** - one segment per directory, last segment is the file. `api`/`e2e` mirror the URL path (`GET /admin/ai-usage` -> `tests/e2e/admin/aiusage.py`); `unit` mirrors the source module path (`devplacepy/utils.py` -> `tests/unit/utils.py`). A test's tier is decided by its fixtures: `page`/`alice`/`bob` = e2e; `app_server`/`seeded_db` or any HTTP call = api; `local_db`-only or no fixture = unit. Run a tier with `make test-unit`/`make test-api`/`make test-e2e`; `make test` runs all three.
Fixture stack: `app_server` (session-scoped uvicorn subprocess on port 10501), `browser_context` (session-scoped Playwright context), `page` (function-scoped, fresh cookies), `alice`/`bob` (seeded logged-in users, `bob` gets its own context for multi-user tests).
Required patterns: every `page.goto(...)`/`page.wait_for_url(...)` MUST pass `wait_until="domcontentloaded"`; prefer `page.locator(...).wait_for(state="visible")` over `wait_for_selector`; scope ambiguous selectors (e.g. comment Delete is `.comment-action-btn:has-text('Delete')`). A test that flips a global `site_settings` value MUST restore it in `try/finally`. Full pitfalls/patterns catalogue is in `tests/CLAUDE.md`.
**Always run the full test suite (`make test` - unit, api, and e2e, every test) as the final validation of every change.** No tier may be skipped and no subset substituted for the whole. The clean import (`python -c "from devplacepy.main import app"`) and per-language manual checks are preliminary gates before the suite, not replacements for it. Any failure is a real signal and blocks completion until fixed.
Tiers, fixtures, required patterns (domcontentloaded, try/finally restores), and the triage loop live in `tests/CLAUDE.md`. The mandate: **full `make test` green as the final validation of every change, no tier skipped, no subset substituted.** Import gate and per-language manual checks are preliminary gates, never replacements.
## Rigorous correctness verification (money, state machines, concurrency)
The persisted test suite (`tests/unit`/`api`/`e2e`) is example-based: it proves the specific inputs someone wrote down behave correctly. It is structurally blind to three classes of bug - a formula wrong at an input nobody tried, an invariant violated only after a long sequence of actions, and a race that only two nearly-simultaneous requests trigger. **Any feature that touches a spendable resource (coins, credits, quotas), a bounded state machine (levels, tiers, counters with a floor/ceiling), or a read-then-write mutation reachable from more than one request path applies this procedure in addition to, not instead of, the normal persisted tests.** A simple CRUD toggle doesn't need it; an economy, inventory, ledger, or scoring feature does. This was built out fully for the Code Farm economy rebalance (see `devplacepy/services/game/CLAUDE.md`, "Every purchase/upgrade is atomic..." - the worked example, including every bug it actually caught) and is the standing procedure for anything shaped like it going forward.
Four escalating layers, run in order, as disposable Python scripts that call the real functions directly against a temp DB (`DEVPLACE_DATABASE_URL`/`DEVPLACE_DATA_DIR` pointed at a scratch file) - not pytest files, unless the user separately asks for persisted tests too:
1. **Property/invariant checks on every pure function, across the full input domain.** For each formula (a reward, a cost curve, a score, a discount), assert the mathematical property it must have - monotonicity, bounds, non-negativity, idempotency, additivity over a partition of its domain - by iterating the real range (hundreds to thousands of values), not a handful of hand-picked spot checks. A monotonicity bug at input 347 is invisible if only 0, 1, and 10 are tried.
2. **Stateful fuzzing.** Build N independent entities, fire a long randomized sequence of every mutating action across all of them against a live temp DB, and re-check invariants after every single action: balances never negative, counters that should only increase never decrease, levels/tiers never exceed their declared bounds. Catch the domain's expected exception type and continue - the goal is catching invariant violations and *unexpected* exceptions, not asserting every action succeeds. This proves safety (nothing bad happens) but not liveness (legitimate actions actually succeed) - a bug that wrongly blocks a valid action just raises a well-formed expected exception and sails through a pure fuzz test undetected. Layer 3 exists because of exactly this gap.
3. **Concurrency: prove races are closed, never infer it from luck.** Any read-then-write mutation reachable from more than one worker process (`uvicorn --workers N`) is a TOCTOU race until proven otherwise. Test with **real separate OS processes**, not threads in one process - `dataset` gives each thread its own pooled connection, and enough threads exhausts that pool and produces `database is locked` noise that is a test-harness artifact, not a finding about the application. Set up genuinely fresh, production-representative state before racing - **never pre-seed or zero a column that the real code path leaves unset/NULL.** This was the single most expensive mistake made building this procedure: a first race-safety pass "passed" only because its own setup script had artificially pre-zeroed columns that a real fresh row leaves as SQL `NULL` - silently hiding the exact bug the fix was supposed to prevent (`NULL = 0` evaluates to `NULL`, not true, in a SQL `WHERE` clause; any column not written in the row's original `INSERT` needs `COALESCE(column, 0)` in every later precondition and every arithmetic `SET`, not a bare comparison). Fire many concurrent attempts at the same resource, assert the exact right number succeed, and verify the final state matches the hand-computed expected total exactly (currency spent, levels advanced) - not just "the others were blocked." Fix a real race with a single atomic conditional SQL statement at the exact chokepoint (`UPDATE ... SET ... WHERE <precondition>`, checked via the driver's real `rowcount` - `dataset`'s wrapped `db.query()` does not expose it, use `db.executable.execute(sqlalchemy.text(...), params).rowcount` inside `with db:`), not a client-side lock or an optimistic-locking library this codebase doesn't otherwise use.
4. **Static analysis beyond `py_compile`.** A clean `python -m py_compile` and a clean `from devplacepy.main import app` only prove syntax and module-load order - neither catches a missing import inside a function body, which is a runtime `NameError` invisible until that exact line executes. Run `pyflakes`/`ruff check` on every touched file before calling a change done; it is nearly free and catches an entire class of bug that layers 1-3 can each individually miss if they don't happen to exercise the broken line.
Spendable resources, bounded state machines, and multi-worker read-then-write mutations additionally require the four-layer procedure (property checks, stateful fuzzing, real-process races, `pyflakes`/`ruff`): see `tests/CLAUDE.md` ("Rigorous correctness verification").
## Feature workflow
Every feature in DevPlace is **one data source fanning out into several consumers**. DevPlace has no isolated change - internalize this before editing. A single handler in `routers/{area}.py` is simultaneously the **four faces of one route**:
1. **HTML** - `respond()` returns a rendered template for browsers.
2. **JSON** - the SAME `respond(..., model=XOut)` returns JSON when `Accept: application/json`. The `*Out` schema is the gate: a context key not declared on `*Out` is silently dropped from JSON even though the template still sees it.
3. **Agent tool** - `services/devii/actions/catalog/` (the relevant module inside the package, e.g. `posts.py`, `admin.py`) exposes the route as an `Action` so Devii can call it on the user's behalf. `requires_auth` mirrors the route guard.
4. **Documented endpoint** - `docs_api.py` `endpoint()` describes it (params, auth, `sample_response`) in the right group, rendered at `/docs/{group}.html`.
A new public read almost always needs all four. The cardinal failure mode is changing one face and forgetting a connected one - a real worked example (followers/following listing) touched nine files across data helpers, output schema, route, view, agent tool, API docs, and the docs trio below for one conceptual feature; that count is the norm, not the exception. If a change touches only one file, confirm none of the four faces were missed. Checklist, ordered by data flow:
1. **Understand.** Read the router, template, matching tests (per the tier naming rule above), and the matching nested `CLAUDE.md`. Trace input model -> router -> data helper -> response (HTML and JSON).
2. **Data layer.** `database/` for query/batch helpers (never inline N+1 loops - use `get_users_by_uids`, `build_pagination`, `_in_clause`; guard raw SQL with `if "table" in db.tables`). `models/` for the Pydantic `Form` input model (add the class to the matching domain module and to the re-export list plus `__all__` in `models/__init__.py`). `schemas/` for the `*Out` JSON response model - every context key a JSON route exposes via `respond(..., model=XOut)` MUST exist on `XOut` or it is silently dropped. Schema auto-syncs via `dataset`; add indexes in `init_db()` with `CREATE INDEX IF NOT EXISTS`.
3. **Server layer.** Handler with the right auth guard (`get_current_user` public read, `require_user` member POST, `require_admin` admin). Specific paths (`/{username}/followers`) declared before catch-alls (`/{username}`). Return HTML+JSON via `respond(request, template, ctx, model=XOut)` or pure JSON via `JSONResponse`. Register any NEW router in `main.py`.
4. **View layer.** Extend `base.html`; page CSS in `{% block extra_head %}`, page JS in `{% block extra_js %}`. Reuse partials and template globals. JS is ES6 modules, one class per file, instantiated on `app`.
5. **Safety layer (skip only when the feature stores nothing and shows nothing).** If the feature adds a surface that carries user-generated content, register it in `database/moderation.py` `REPORTABLE_TARGETS` (or in `UNREPORTABLE_TABLES` with a reason), resolve it in `resolve_object_url`, and include `_report_button.html` in its action bar - the registry test and the e2e coverage test both fail otherwise. If it collects or transmits a new *category* of personal data, or sends anything new to a third party, update `/docs/privacy.html` and the app-store privacy declarations in the same change; that disclosure is part of the feature, not a follow-up.
6. **Agent + docs layer (the most-forgotten step - do not skip).** `services/devii/actions/catalog/` (the relevant module inside the package) - add an `Action` tool if a user could ask Devii to do this (`requires_auth=False` for public reads). `docs_api.py` - every public/auth endpoint gets an `endpoint()` entry with params and a `sample_response`. `routers/docs/pages.py` `DOCS_PAGES` for prose pages. SEO (`seo.py`) - `base_seo_context` and any JSON-LD for a new public page; add to `routers/seo.py` sitemap if indexable.
7. **Document.** `README.md` (product-facing, routes/config/dependencies/user-visible features), the relevant nested `CLAUDE.md` (any new mechanic, helper, pitfall, or cross-layer wiring), this root `CLAUDE.md` only when a NEW architectural rule or workflow step is introduced (not per feature).
8. **Validate.** Confirm a clean import (`python -c "from devplacepy.main import app"`), check each touched language manually, grep for em-dash in touched files (neither the character nor its HTML entity - use a hyphen), and run `pyflakes`/`ruff check` on every touched file. **If the feature touches a spendable resource, a bounded state machine, or a read-then-write mutation reachable from more than one request path, also run the four-layer procedure in "Rigorous correctness verification" above** - it is the default for that shape of feature, not an optional extra. **Finish by running the full persisted test suite (`make test` - every tier, every test) and fixing any failure before the change is done.** Write new tests in the matching tier/path, following the required patterns above.
Failures at any implementation step block the workflow - never skip a failed step.
Every feature is one data source fanning out into HTML, JSON, a Devii action, and a documented endpoint. The ordered checklist (understand, data, server, view, safety, agent+docs, document, validate) lives in `devplacepy/routers/CLAUDE.md` ("Feature checklist"). Failures at any step block the workflow.
## CI/CD
+8
View File
@@ -265,3 +265,11 @@ Posts, gists, projects and news carry one status from `VISIBILITY_VALUES`: `publ
- **Backwards compatibility (hard rule).** `visibility` is optional on every API: `VisibilityCreateMixin` defaults to `published`, `VisibilityEditMixin` defaults to `None` meaning keep the current value (never reset to published), NULL rows read as published, and the docs/Devii parameter descriptions say so (`tests/unit/docs_api/visibility.py`, `tests/api/content/visibility.py` legacy-client tests). Never make the field required.
- **Outputs.** `VisibleOut` (`schemas/content.py`) gives `PostOut`/`GistOut`/`ProjectOut` a `visibility` that reads NULL as `published`. Forms use `VisibilityCreateMixin` (default `published`) and `VisibilityEditMixin` (`None` keeps the current value); `VisibilityForm{value}` backs the admin news route.
- **Adding a table.** Put it in `VISIBILITY_COLUMNS` and `TARGET_TABLES`, add its form mixin and Out base, apply `listed_clause`/`listed_sql` to each new read, and extend `tests/api/content/visibility.py`. `tests/unit/database/visibility.py` asserts the spec is self-consistent.
## Notification grouping, throttling and keyboard settings
`users` carries `enter_to_submit`, `notif_grouping_enabled` and `notif_throttle_enabled` (all default 1, ensured in `schema.py`, owner-or-admin toggles on the profile page).
## Data CLI
`devplace apikey backfill` assigns keys to users that lack one. `devplace attachments prune` removes orphan attachment records/files. `devplace system prune` (with `--dry-run`) purges soft-deleted attachment/project-file blobs, sweeps blob files with zero DB reference, and GCs orphaned container workspace dirs. `database/notifications.py` owns the single grouping specification: `NOTIFICATION_GROUP_KEYS` (actor / target / single per type, unlisted types are single), `notification_group_key(row)`, and `count_unread_groups(user_uid)` (groups when enabled, rows when off). Every badge producer calls `count_unread_groups`; none counts rows itself. Delivery throttling (item 5) reuses the same key.
+18
View File
@@ -382,3 +382,21 @@ The profile **Activity** tab (`/profile/{username}?tab=activity`, public) interl
## Content visibility routes
Posts, gists, projects and news share one four-value status (published, hidden, draft, offline); the specification, truth table and choke points are in `devplacepy/database/CLAUDE.md` ("Content visibility"). It is an ordinary field of the create and edit forms of posts, gists and projects (`visibility`, via the `_visibility_field.html` partial), handled by `create_content_item` and `edit_content_item` like every other field; there are no dedicated toggle routes. The only dedicated route is the administrator's `POST /admin/news/{uid}/visibility` (`VisibilityForm{value}`), because news has no edit form. Hidden items are `noindex,nofollow`. Comments, votes, reactions, bookmarks and notes refuse (404) a target the viewer cannot open (`content.can_view_target`), and the saved/notes lists skip such targets. The devRant API resolves rants through `post_by_id(rant_id, viewer)` and lists listed rants only. Audit key: `<kind>.visibility.set`. Devii: the `visibility` parameter on the create and edit tools, plus `admin_set_news_visibility`.
## Notifications grouping and profile settings (requested_changes items 1, 4, 5)
- `POST /profile/{username}/enter-to-submit`, `POST /profile/{username}/notifications/grouping` and `POST /profile/{username}/notifications/throttling` are owner-or-admin toggles through `routers/profile/_shared.resolve_customization_target`, audited as `profile.enter_to_submit.toggle`, `profile.notification.grouping.toggle` and `profile.notification.throttle.toggle`.
- `GET /notifications` groups events with `notification_group_key` when the recipient has grouping on (250 row fetch cap, 25 groups per page, date groups outside event groups). Opening or dismissing a grouped card marks every member read. With grouping off the page and badge keep the old one-row behaviour.
## Feature checklist (one data source, four faces)
Every feature is one data source fanning out into HTML, JSON (`respond(..., model=XOut)`; a context key not on `XOut` is silently dropped from JSON), a Devii agent action, and a documented endpoint. A change touching one file must confirm none of the four faces were missed. Checklist, ordered by data flow:
1. **Understand.** Read the router, template, matching tests, and the nested `CLAUDE.md`. Trace input model, router, data helper, response (HTML and JSON).
2. **Data layer.** `database/` for query/batch helpers (never inline N+1; guard raw SQL with `if "table" in db.tables`). `models/` for the Pydantic `Form` (add to the domain module, re-export list, and `__all__`). `schemas/` for the `*Out` JSON model; every context key a JSON route exposes must exist on it. Indexes via `CREATE INDEX IF NOT EXISTS` in `init_db()`.
3. **Server layer.** Guard matches the read (public), write (member), or admin surface. Specific paths before catch-alls. HTML+JSON via `respond(...)` or pure JSON via `JSONResponse`. Register any new router in `main.py`.
4. **View layer.** Extend `base.html`; page CSS/JS via `extra_head`/`extra_js`. Reuse partials and template globals. ES6 modules, one class per file, instantiated on `app`.
5. **Safety layer (skip only when the feature stores and shows nothing).** New user-generated surface: register in `REPORTABLE_TARGETS` (or `UNREPORTABLE_TABLES` with reason), resolve in `resolve_object_url`, include `_report_button.html`. New personal-data category or third-party transmission: update `/docs/privacy.html` and the app-store declarations in the same change.
6. **Agent + docs layer.** Devii `Action` where a user could ask for this (`requires_auth` mirrors the guard). `docs_api.py` `endpoint()` with params and `sample_response`. `DOCS_PAGES` prose. `seo.py` context and sitemap entry for new public pages.
7. **Document.** `README.md` for product-facing surface; the nested `CLAUDE.md` for any new mechanic or cross-layer wiring; root `CLAUDE.md` only for a new architectural rule or workflow step.
8. **Validate.** Import gate, per-language manual checks, no em dashes, `pyflakes`/`ruff check` on every touched file, the four-layer rigor procedure for spendable/state-machine/race shapes, then full `make test` green before done. Failures at any step block the workflow.
+5 -1
View File
@@ -31,7 +31,11 @@ Each project carries a virtual filesystem so it can hold a whole software projec
## Project visibility and read-only
Two owner-controlled flags on the `projects` row, both integer `0`/`1` (default `0`, set on the create insert so the columns always exist): `is_private` hides the project from other viewers, `read_only` freezes its filesystem against every mutation. **The full security predicates** (`content.can_view_project`, `owns_instance`, `can_view_project_containers`, `can_view_instance`, `can_manage_instance`, the primary-administrator container isolation rules) are documented once in the root CLAUDE.md's "Project visibility (`is_private`) and read-only" section - this file covers only the project-page/filesystem UI-level behavior that sits on top of those predicates.
Two owner-controlled flags on the `projects` row, both integer `0`/`1` (default `0`, set on the create insert so the columns always exist): `is_private` hides the project from other viewers, `read_only` freezes its filesystem against every mutation. **The full security predicates** (documented once, here):
- Project visibility (`is_private`) and read-only (`read_only`) are owner-controlled flags on `projects`. Read access is gated by the single `content.can_view_project(project, user)` predicate at EVERY read surface, never re-implemented inline. Predicate: `not is_private OR is_owner OR (is_admin AND owner is not an admin)`.
- Containers have their own, stricter isolation predicates (`owns_instance`, `can_view_project_containers`, `can_view_instance`, `can_manage_instance`): the primary administrator sees/manages every container; any other admin can VIEW others' containers only on public projects and can MANAGE only instances they own.
- Read-only is enforced as a single data-layer guard `project_files._guard_writable(project_uid)` at the top of every mutation entrypoint; add it to any NEW file-mutating function. Devii may flip read-only/visibility only after explicit confirmation.
**Toggle routes** (owner-only, `routers/projects/index.py`): `POST /projects/{slug}/private` and `POST /projects/{slug}/readonly`, each taking `ProjectFlagForm{value: bool}` and routed through `_set_project_flag`. The create form carries an `is_private` checkbox (`ProjectForm.is_private`); `project_detail.html` shows Private/Read-only badges and owner toggle buttons (**both** the private and read-only buttons carry `data-confirm` so `ModalManager.initConfirmations` gates them through `app.dialog`), and `project_files.html` hides the editing toolbar + shows a banner when read-only. Schemas: `is_private`/`read_only` on `ProjectOut` and `ProjectDetailOut`, `read_only`/`is_private` on `ProjectFilesOut`.
+1 -1
View File
@@ -12,7 +12,7 @@ Admin-only. Supervises container instances, all running one shared prebuilt imag
Mounting the docker socket is root-equivalent on the host. Every run/exec/lifecycle/schedule operation is gated `require_admin` (HTTP) and `requires_admin=True` (Devii). `--privileged` is never passed. User input is never shell-interpolated - every call is an arg-list subprocess, never `shell=True`. Resource limits are applied via `--cpus`/`--memory`.
On top of the admin gate, **per-user container isolation** applies (see root CLAUDE.md "Project visibility (is_private) and read-only" convention): only the **primary administrator** (earliest-created Admin) and the instance owner (creator or project owner) may manage an instance; other admins get read-only access, and only when the instance's project is public. Enforced via `content.py` predicates `owns_instance`, `can_view_project_containers`, `can_view_instance`, `can_manage_instance` (all reusing `is_primary_admin`): the primary administrator sees and manages every container including those on private projects; any other admin can VIEW containers of others only when the instance's project is public (private-project containers of others are invisible; of private containers they see only their own), and can MANAGE (edit/lifecycle/exec/terminal/sync/delete/schedules) only instances they own - non-owners get 403 plus an audit row with `result="denied"` (WS close `1008`). This is enforced at every entrypoint: `routers/projects/containers/` (`project_for` + `manage_guard` + the exec WS), the admin Containers manager (`_decorate` filtering + per-row `can_manage`, `_viewable_instance_or_404`, `_manage_denied`, create + project-search), the Devii container tools (`ContainerController._project` + `_require_manage`), and the live view relay (broadcast topics never carry private-project instances).
On top of the admin gate, **per-user container isolation** applies (predicates documented once in `devplacepy/routers/projects/CLAUDE.md` "Project visibility and read-only" (is_private) and read-only" convention): only the **primary administrator** (earliest-created Admin) and the instance owner (creator or project owner) may manage an instance; other admins get read-only access, and only when the instance's project is public. Enforced via `content.py` predicates `owns_instance`, `can_view_project_containers`, `can_view_instance`, `can_manage_instance` (all reusing `is_primary_admin`): the primary administrator sees and manages every container including those on private projects; any other admin can VIEW containers of others only when the instance's project is public (private-project containers of others are invisible; of private containers they see only their own), and can MANAGE (edit/lifecycle/exec/terminal/sync/delete/schedules) only instances they own - non-owners get 403 plus an audit row with `result="denied"` (WS close `1008`). This is enforced at every entrypoint: `routers/projects/containers/` (`project_for` + `manage_guard` + the exec WS), the admin Containers manager (`_decorate` filtering + per-row `can_manage`, `_viewable_instance_or_404`, `_manage_denied`, create + project-search), the Devii container tools (`ContainerController._project` + `_require_manage`), and the live view relay (broadcast topics never carry private-project instances).
## One shared image, no in-app builds (load-bearing)
+4
View File
@@ -139,3 +139,7 @@ The client side is `static/js/TermsGate.js` (`app.termsGate`); see `devplacepy/s
- A new filter category: add rules to `rules.py` and the reason key to `REPORT_REASONS`; a unit test asserts every rule's category is a real reason.
- A new consent: add it to `CONSENT_KINDS` and enforce it at one choke point, never at N call sites.
- Never add a second removal path, a second suspension check, or a second consent gate.
## Account deletion CLI
`devplace accounts pending` lists deleted accounts awaiting purge; `devplace accounts prune` (with `--dry-run` to preview) permanently purges accounts past the deletion grace window.
+4
View File
@@ -45,6 +45,10 @@ Per article up to `IMG_PER_ARTICLE=5` candidate image URLs (from `_get_article_i
After the per-article loop, `_apply_landing_selection` queries recent (`<= LANDING_RECENCY_DAYS`) rows that are published + featured + `has_unique_image` + NOT `landing_locked`, sorts by `(-grade, -synced_at)`, sets `show_on_landing=1` for the top `LANDING_MAX` with `grade >= LANDING_MIN_SCORE` and `show_on_landing=0` for the rest of THAT service-managed set (self-rotating). When an admin manually toggles Featured or Landing (`routers/admin/news.py`), the matching `featured_locked`/`landing_locked` is set to 1 so the service stops auto-managing that row; updates of a locked Featured row never overwrite `featured`. New `news` columns: `ai_grade`, `featured`, `has_unique_image`, `image_url`, `featured_locked`, `landing_locked`, `author`, `article_published` (all added to the `init_db` ensure-block - the stale-schema rule). Audit events `news.service.ingest`/`news.service.publish`/`news.service.draft`/`news.service.reject`/`news.service.landing` (`record_system`, category `news`). New dep: `imagehash` (`Pillow` already present).
## CLI
`devplace news clear` deletes every news row; `devplace news sanitize` strips HTML from news descriptions/content.
## Editorial labels are admin-only on the public surfaces
The `&#x2605; Featured` badge and the `Grade {{ grade }}` chip are internal editorial signals, so on every PUBLIC news surface - the `/news` listing (`news.html`), the article page (`news_detail.html`), and the landing/home Developer News cards (`landing.html`) - both are wrapped in `{% if is_admin(user) %}`. Members and guests never see them; administrators still see them everywhere (including the public pages) and the admin **Manage News** area (`admin_news.html`) is unchanged, where the grade and featured state are the editorial controls. The article's source name and timestamp stay visible to everyone. Gating only the rendered labels does not touch the stored `grade`/`featured` columns, the grading/landing logic, or ordering (`/news` is still ordered by effective `grade`).
+1 -1
View File
@@ -126,7 +126,7 @@ and the post page is the surface. `serialize_war` is the single card/JSON shape
## Verification
The feature is a spendable resource + bounded state machine + multi-path read-then-write, so the
root CLAUDE.md four-layer procedure applies to any change here: property checks on `rules.py`
four-layer procedure in `tests/CLAUDE.md` ("Rigorous correctness verification") applies to any change here: property checks on `rules.py`
across the full domain, stateful fuzz asserting `war.hp_x == SUM(fighters.hp_x)` and
`coins >= 0` after every action, and REAL multi-process races (concurrent fight = exactly one
lands and exactly one fee; two wars vs 1.5x the fee = exactly one lands; concurrent resolve =
+9 -3
View File
@@ -20,9 +20,9 @@ Self-contained, presentational UI is built as custom elements with the `dp-` pre
**Prompt seeding on the shared Devii opener (`data-devii-prompt`).** `DeviiTerminal.bindTriggers` binds every `[data-devii-open]` element; it now reads `trigger.dataset.deviiPrompt` and passes it to `DeviiTerminal.open(prompt)`, which calls `this.element.open()` and then `devii-terminal.prefill(text)` (sets `this.input.value`, moves the caret to the end, focuses). **It never auto-sends** - the member reads the request and presses Enter, keeping the assistant's first action explicitly user-initiated. This is a platform-wide capability available to any page, not a quiz-only shim: add `data-devii-prompt="..."` beside `data-devii-open` and the terminal opens pre-filled.
`dp-chat` (`AppChat.js`) is the Slack-like DM chat widget that fully replaced the old page-controller trio `MessagesLayout.js`/`MessagesSocket.js`/`MessageSearch.js` (deleted) and `static/css/messages.css` (superseded by `static/css/chat.css`) on `/messages`. Unlike every other component here, it does NOT build its DOM from scratch on `connectedCallback` when server-rendered light-DOM children already exist (`mode="page"`) - it **adopts** the existing `.messages-list`/`.messages-main`/`.messages-thread`/`.message-bubble` markup `templates/messages.html` still renders (so no-JS and crawler fallback both keep working) and only builds a from-scratch skeleton when none is present (`mode="embed"`, a standalone `<dp-chat mode="embed" self-uid="..." with-uid="..." send-url="..." ws-url="...">` usable outside `/messages`). It owns its own `ChatSocket` instance, the conversation search dropdown (absorbed from the old `MessageSearch.js`, still built on the shared `ListNav` utility), consecutive-message grouping (`chat/MessageGrouping.js`), a working optimistic send with `.pending`/`.failed` (tap-to-retry) bubble states, and an opt-in (`ai-indicator` attribute) "Adjusted by AI" caption shown when a reconciled echo's `ai_processed` frame flag is true and the content changed from what was locally typed - never a diff/revert UI, the backend keeps no pre-correction copy to diff against. Presence needs no component code at all: the adopted markup keeps its `data-presence-uid` attributes, so the page-global `PresenceManager` (below) already drives it, and the conversation list it builds live uses the shared `Avatar.badgeElement(user)` rather than hand-rolled dot markup. In `mode="embed"`, where no page-global instance may exist, it constructs a root-scoped `PresenceManager` instead of re-implementing presence - `dp-chat` owns no presence logic of its own. The message body itself keeps rendering through `<dp-content>` (see "CLIENT-only now" below) - the redesign only removed the historical `no-copy` attribute on message bubbles so `dp-content`'s own existing `.content-copy-btn` doubles as the hover/focus-reveal action toolbar's Copy button (§6.3 of the design doc it was built from), instead of a second copy mechanism being hand-rolled.
`dp-chat` (`AppChat.js`) is the Slack-like DM chat widget that fully replaced the old page-controller trio `MessagesLayout.js`/`MessagesSocket.js`/`MessageSearch.js` (deleted) and `static/css/messages.css` (superseded by `static/css/chat.css`) on `/messages`. Unlike every other component here, it does NOT build its DOM from scratch on `connectedCallback` when server-rendered light-DOM children already exist (`mode="page"`) - it **adopts** the existing `.messages-list`/`.messages-main`/`.messages-thread`/`.message-bubble` markup `templates/messages.html` still renders (so no-JS and crawler fallback both keep working) and only builds a from-scratch skeleton when none is present (`mode="embed"`, a standalone `<dp-chat mode="embed" self-uid="..." with-uid="..." send-url="..." ws-url="...">` usable outside `/messages`). In `page`/`embed` mode it owns its own `ChatSocket` instance (`window` mode subscribes through the dock hub, see `dp-chat-dock` below). It owns the conversation search dropdown (absorbed from the old `MessageSearch.js`, still built on the shared `ListNav` utility), consecutive-message grouping (`chat/MessageGrouping.js`), a working optimistic send with `.pending`/`.failed` (tap-to-retry) bubble states, and an opt-in (`ai-indicator` attribute) "Adjusted by AI" caption shown when a reconciled echo's `ai_processed` frame flag is true and the content changed from what was locally typed - never a diff/revert UI, the backend keeps no pre-correction copy to diff against. Presence needs no component code at all: the adopted markup keeps its `data-presence-uid` attributes, so the page-global `PresenceManager` (below) already drives it, and the conversation list it builds live uses the shared `Avatar.badgeElement(user)` rather than hand-rolled dot markup. In `mode="embed"`, where no page-global instance may exist, it constructs a root-scoped `PresenceManager` instead of re-implementing presence - `dp-chat` owns no presence logic of its own. The message body itself keeps rendering through `<dp-content>` (see "CLIENT-only now" below) - the redesign only removed the historical `no-copy` attribute on message bubbles so `dp-content`'s own existing `.content-copy-btn` doubles as the hover/focus-reveal action toolbar's Copy button (§6.3 of the design doc it was built from), instead of a second copy mechanism being hand-rolled.
`dp-chat-dock` (`AppChatDock.js`, `app.chatDock`) is the Facebook-style docked chat, server-rendered once in `base.html` (block `chat_dock`, members only; `messages.html` empties the block so `/messages` has no dock). It builds the **Chats panel** (opened by any `[data-chat-panel-toggle]`, the topnav Messages icon; people search via `ListNav`, recent conversations from `/messages/conversations`, a New message compose window) and a bottom-right **tray** of chat windows plus minimized avatar heads. Each window is a plain `dp-chat` with `mode="window"`, so every chat behaviour (optimistic send, reconcile, AI frames, typing, receipts, delete, report, attachments, older history) is the one `AppChat` implementation. Rules that keep it correct: window `dp-chat` elements are **never moved in the DOM** (moving a custom element runs `disconnectedCallback`, which closes its socket channel, and the `_built` guard skips the rebuild), so windows are appended in creation order and removed, never reordered; a minimized window is destroyed and re-created on expand, which reloads its history and marks it read, so a head never marks anything read; open/minimized state lives in `sessionStorage` (per tab, the `ScrollMemory` precedent) under `devplace.chat-dock.<uid>`; at the 768px mobile breakpoint the dock renders nothing and every trigger falls through to its `href` (the full `/messages` page). Any element with `data-chat-open="<uid>"` (plus `data-chat-username`/`data-chat-avatar-seed`, emitted by the `_chat_open_attrs.html` partial) opens a window on click: the profile Send Message button and the `/notifications` card link of a `message` notification use it, and `LiveNotifications` routes a `message` toast's click through `app.chatDock.open()` and falls back to the URL when it returns `false`. All windows share ONE WebSocket through `chat/ChatSocketHub.js`: `subscribe(handlers)` returns a channel with the `ChatSocket` surface (`send`/`isOpen`/`close`, where `close` unsubscribes), the socket opens on the first subscriber and closes with the last, and a late subscriber gets `onReady` on a microtask. A `dp-chat` given `.hub` subscribes instead of opening its own socket, and drops `error` frames whose `client_id` is not one of its own pending sends. `chat/ConversationItem.js` is the one `.conversation-item` builder shared by `/messages` and the dock. `dp-chat` dispatches a bubbling `dp-chat:conversation` event (detail `{user}`) after it renders a conversation, which the dock uses to learn a window's partner name and to refresh the unread counters.
`dp-chat-dock` (`AppChatDock.js`, `app.chatDock`) is the Facebook-style docked chat, server-rendered once in `base.html` (block `chat_dock`, members only; `messages.html` empties the block so `/messages` has no dock). It builds the **Chats panel** (opened by any `[data-chat-panel-toggle]`, the topnav Messages icon; people search via `ListNav`, recent conversations from `/messages/conversations`, a New message compose window) and a bottom-right **tray** of chat windows plus minimized avatar heads. Each window is a plain `dp-chat` with `mode="window"`, so every chat behaviour (optimistic send, reconcile, AI frames, typing, receipts, delete, report, attachments, older history) is the one `AppChat` implementation. Rules that keep it correct: window `dp-chat` elements are **never moved in the DOM** (moving a custom element runs `disconnectedCallback`, which closes its socket channel, and the `_built` guard skips the rebuild), so windows are appended in creation order and removed, never reordered; a minimized window is destroyed and re-created on expand, which reloads its history and marks it read, so a head never marks anything read; open/minimized state lives in `sessionStorage` (per tab, the `ScrollMemory` precedent) under `devplace.chat-dock.<uid>`, cleared when a logout link is clicked; minimized-head unread counts are reconciled against `/messages/conversations` on connect and on panel open, so reading elsewhere never leaves a stale badge; at the 768px mobile breakpoint the dock renders nothing and every trigger falls through to its `href` (the full `/messages` page). Any element with `data-chat-open="<uid>"` (plus `data-chat-username`/`data-chat-avatar-seed`, emitted by the `_chat_open_attrs.html` partial) opens a window on click: the profile Send Message button and the `/notifications` card link of a `message` notification use it, and `LiveNotifications` routes a `message` toast's click through `app.chatDock.open()` and falls back to the URL when it returns `false`. All windows share ONE WebSocket through `chat/ChatSocketHub.js`: `subscribe(handlers)` returns a channel with the `ChatSocket` surface (`send`/`isOpen`/`close`, where `close` unsubscribes), the socket opens on the first subscriber and closes with the last, and a late subscriber gets `onReady` on a microtask. A `dp-chat` given `.hub` subscribes instead of opening its own socket, and drops `error` frames whose `client_id` is not one of its own pending sends. `chat/ConversationItem.js` is the one `.conversation-item` builder shared by `/messages` and the dock. `dp-chat` dispatches a bubbling `dp-chat:conversation` event (detail `{user}`) after it renders a conversation, which the dock uses to learn a window's partner name and to refresh the unread counters.
`static/js/chat/ChatSocket.js` and `static/js/chat/MessageGrouping.js` are chat-scoped helpers used only by `AppChat.js` - `ChatSocket` is modeled on `PubSubClient.js`'s real exponential backoff (200ms doubling to a 5000ms cap, reset on a successful connect) rather than the flat-delay retry the deleted `MessagesSocket.js` used, and preserves the same `4013` "wrong worker" fast-retry special case. `MessageGrouping.shouldGroup(previous, current)` is the one pure predicate (<=300s gap, same sender) shared by both the initial-history grouping pass and the live-append path, so the two can never disagree. Neither file is a general-purpose "do not reimplement" utility for the rest of the app (see the out-of-scope note in the design document this shipped from) - they are not added to the do-not-reimplement list below; a future non-chat WebSocket feature should keep hand-rolling its own client (as `DeviiSocket.js`/`DeepsearchProgressSocket.js`/`SeoProgressSocket.js`/`AppDeepsearchChat.js`'s inline socket already do) rather than reaching into `chat/`.
@@ -32,7 +32,7 @@ Conventions:
- **Light DOM only** (no `attachShadow`), so the site's global CSS applies - matching the existing `devii-*` elements. `dp-dialog`/`dp-context-menu` reuse the existing `.dialog-*`/`.context-menu*` styles in `components.css`; `dp-toast` styles are in `components.css` (`.dp-toast-host`/`.dp-toast`).
- Each file self-registers via `customElements.define` at the bottom. `components/index.js` imports them all and is imported by `Application.js`, so every element is defined on every page (including `/docs`).
- The behavioural singletons are created once in `Application.js` and exposed as `app.dialog`, `app.contextMenu`, `app.toast`. The `dp-dialog`/`dp-context-menu` elements keep the exact pre-existing `Dialog`/`ContextMenu` APIs (`confirm`/`prompt`/`alert`/`open`, `attach`/`open`/`close`) so existing callers (`ProjectFiles`, `ApiKeyManager`, `ModalManager`, `PushManager`, `ApiTester`) are unchanged. `Avatar`/`CodeBlock`/`Toast`/`ContentRenderer` remain as static/service modules (widely imported); the matching elements (`dp-avatar`, `dp-code`, `dp-content`) reuse them. `dp-content` wraps the shared `contentRenderer` engine that also powers the `data-render` attribute (driven by `ContentEnhancer`) - the engine stays a reusable service, the element is its component face. `dp-content` captures its raw markdown source before `contentRenderer.applyTo` overwrites `textContent`, then mounts a hover/focus reveal `.content-copy-btn` in its top-right corner that copies that original source to the clipboard (mirroring `CodeBlock.copyButton`); CSS lives beside `.code-copy-btn` in `docs.css`.
- **`dp-content` / `dp-title` are CLIENT-only now (live contexts).** `dp-content` (`AppContent.js`) and its inline companion `dp-title` (`AppTitle.js`, `contentRenderer.renderInline`) render markdown/emoji/media (and, for title, inline-only with an inline-tag allowlist) on the client from `textContent`. **They are no longer used for server-rendered content/titles** - those moved to the backend `render_content`/`render_title` globals (see the root CLAUDE.md "Content rendering pipeline" section) for SEO. The components remain defined and are used only where content is generated client-side after load: `dp-content` in the DeepSearch chat (`AppDeepsearchChat.js`) and the planning report (`PlanningGenerator.js` -> `admin_issues_planning.html`). Keep them for those live cases and future use; do NOT wrap server-known content/titles in them. Both are now used ONLY for live/client-generated content (chat, planning report, dynamically inserted bubbles); server-rendered content/titles use the backend `render_content`/`render_title` globals instead. The components are intentionally kept for those live contexts and future use.
- **`dp-content` / `dp-title` are CLIENT-only now (live contexts).** `dp-content` (`AppContent.js`) and its inline companion `dp-title` (`AppTitle.js`, `contentRenderer.renderInline`) render markdown/emoji/media (and, for title, inline-only with an inline-tag allowlist) on the client from `textContent`. **They are no longer used for server-rendered content/titles** - those moved to the backend `render_content`/`render_title` globals (see `devplacepy/templates/CLAUDE.md` "Content rendering pipeline") for SEO. The components remain defined and are used only where content is generated client-side after load: `dp-content` in the DeepSearch chat (`AppDeepsearchChat.js`) and the planning report (`PlanningGenerator.js` -> `admin_issues_planning.html`). Keep them for those live cases and future use; do NOT wrap server-known content/titles in them. Both are now used ONLY for live/client-generated content (chat, planning report, dynamically inserted bubbles); server-rendered content/titles use the backend `render_content`/`render_title` globals instead. The components are intentionally kept for those live contexts and future use.
- **What is NOT a component (by design):** partial-bound controllers (`ReactionBar`, `VoteManager`, `BookmarkManager`, `PollManager`, `CommentManager`, etc.) enhance server-rendered `_*.html` markup rather than render standalone UI; pure utilities (`Http`, `DomUtils`, `FormManager`, `Poller`, `JobPoller`, `OptimisticAction`) have no UI. These stay plain ES6 modules. The four optimistic engagement controllers extend the shared `OptimisticAction` base - see "Shared frontend utilities" below. Self-contained presentational widgets become components; partial-bound controllers (votes, reactions, comments) and pure utilities stay plain modules because they enhance server-rendered markup rather than render standalone UI.
- Documented in the public docs **Components** section (`templates/docs/component-*.html`, registered under `SECTION_COMPONENTS` in the `routers/docs` package). Each page has a `data-render` markdown block (with example markup HTML-escaped as `&lt;dp-...&gt;`, since `data-render` re-parses `textContent` and would otherwise instantiate the example) plus a live demo in a separate block whose `<script type="module">` imports its own component module (it runs before `Application.js`).
- **`dp-lightbox` (`AppLightbox.js`, `app.lightbox`, `static/css/lightbox.css`)** is the single image lightbox. It is **attribute-wired, not call-wired**: the singleton installs ONE delegated `document` click listener and opens any clicked `img[data-lightbox]` (showing `data-full` when present, else the image's own src; `alt` as caption; ignored when the image sits inside an `<a>`). To make a thumbnail open it, just add `data-lightbox` - never attach a click handler. Attachment thumbnails carry `data-lightbox`+`data-full` (`_attachment_display.html`); markdown content images are marked centrally in `ContentEnhancer.initContentRenderer` (one place covers every `data-render` surface), so embedded images are always clickable. The old hand-rolled `.attachment-lightbox` markup/CSS was dead (never wired) and has been removed.
@@ -122,3 +122,9 @@ The component validates size/type/count and reports errors via `app.toast`. CSS
## ReportDialog (`ReportDialog.js`, `app.reportDialog`)
One class, one dialog, every surface. It delegates a document-level click on `[data-report-type]` (emitted by `_report_button.html`), opens the single `#report-dialog` overlay with the standard `.visible` toggle, and submits through `Http.sendForm` to `/reports/{target_type}/{target_uid}`. The toast repeats the published response window returned by the endpoint, so the acknowledgement the user sees is the one the server actually committed to. It carries no reason list of its own - the options are server-rendered from the `REPORT_REASONS` Jinja global, so a client can never offer a reason the API would reject.
## Enter to send (`EnterSubmit.js`)
One shared helper owns Enter behaviour: `EnterSubmit.attach` (composers: comments on every target type and `dp-chat`; Enter submits when the `enter_to_submit` profile setting is on, Shift+Enter newlines, Ctrl+Enter always submits, IME composition and an open mention dropdown always win) and `EnterSubmit.attachEditors` (Ctrl+Enter submit for every other textarea). The setting is exposed as `body[data-enter-to-submit]`. Never add a per-form Enter handler.
Emoji shortcodes map: after an `emoji` dependency bump, regenerate `static/js/emoji-shortcodes.js` with `devplace emoji-sync`, never hand-edit.
+20
View File
@@ -79,6 +79,9 @@ Reuse these via `{% set _x = ... %}{% include %}` (the `_avatar_link.html` conve
- `_report_button.html` - the Report control (and Block, when `_owner_name` is given) for any content action bar. Locals: `_type`, `_uid`, `_owner` (owner uid - the control hides on your own content), `_owner_name` (optional), `_class` (the surrounding surface's button class). Included at fifteen sites; a new content surface MUST include it (see the root `CLAUDE.md` rule).
- `_report_dialog.html` - the one report dialog, included once in `base.html` for signed-in users and driven by `ReportDialog.js`. Reasons come from the `REPORT_REASONS` Jinja global; never hand-roll a second dialog.
- `_maturity_gate.html` - the interstitial rendered in place of a maturity-labelled item. Local: `_level`. Guard the include with the `maturity_hidden(level, user)` global; the item's `maturity` is attached by `enrich_items`/`load_detail`.
- `_card_link.html` - the stretched card link (`<a class="card-link">`). Locals: `_href`, optional `_label`, optional `_chat_user`. Always includes `_chat_open_attrs.html`, so any card link whose `_chat_user` is set becomes a dock chat opener.
- `_chat_open_attrs.html` - emits `data-chat-open`/`data-chat-username`/`data-chat-avatar-seed` (seed via the `avatar_seed()` choke point) when `_chat_user` with a uid is set, and nothing otherwise. `dp-chat-dock` intercepts clicks on any `[data-chat-open]` element and opens a docked window; without JS the enclosing link's `href` still navigates. Set `_chat_user` only on genuine Send Message links (profile, message notifications), never on unrelated cards.
- The `chat_dock` block in `base.html` renders `<dp-chat-dock>` once for signed-in users; `messages.html` empties the block so `/messages` has no dock. The topnav Messages link carries `data-chat-panel-toggle` plus server-rendered `aria-haspopup="dialog"`/`aria-controls="chat-panel"`/`aria-expanded` for the Chats panel.
Vote button styles live ONCE in `feed.css` (`.post-action-btn`) - never redefine them in `post.css`. Page-specific CSS goes in a `static/css/*.css` file referenced from `{% block extra_head %}`, never an inline `<style>` block. All CSS conventions (tokens, `--z-*` stacking bands, breakpoints, reduced motion) are in `devplacepy/static/css/CLAUDE.md`.
@@ -93,3 +96,20 @@ The three public listings (`/feed`, `/gists`, `/projects`) share one search box:
## Visibility partial
- `_visibility_field.html` - the `<select name="visibility">` for create and edit forms. Locals: `_visibility` (current value, default `published`), `_visibility_id` (unique element id). Options come from the `VISIBILITY_OPTIONS` global; `visibility_of(table, item)` and `visibility_label(value)` are the other globals. The admin news table reuses the generic `data-auto-submit` select pattern from `admin_users.html`.
## Action menus and composer order (requested_changes items 2 and 3)
- Creation forms put the title first (`_post_composer_form.html` leads with `#post-title`; projects, gists, issues, quizzes already did). Title inputs in modals carry `data-autofocus`; `ModalManager` prefers it on open. News has no creation form.
- Every content action bar (post, project, gist, news, quiz detail and post/quiz cards) keeps votes, reactions, the main call to action and Note primary, and groups the rest into the one existing `dp-action-menu`. Card menus never hardcode panel ids. `_bookmark_button.html` and `_report_button.html` take `_menu_action = true` inside a menu.
## Content rendering pipeline (backend, `devplacepy/rendering.py`)
Server-rendered content and titles are the default for everything that exists at request time (post bodies, comments, news, project/gist descriptions, DM history, every content title). Jinja globals `render_content(text)`/`render_title(text)`, mirrored client pipeline via mistune, `@lru_cache`d. Server-rendered code blocks get highlighting plus Copy client-side via `ContentEnhancer`.
The client pipeline (`ContentRenderer.js`, `dp-content`/`dp-title`) is ONLY for live content that does not exist at request time (live comments, DM bubbles, Devii/DeepSearch/Docs chat, planning report): marked, then `DOMPurify.sanitize` (fail-closed), then highlight.js and media/autolink. Never add `data-render` to server-rendered content.
Rules: emoji shortcodes are the full GitHub/Discord set, generated by `rendering.py` `build_emoji_shortcodes()` with the identical map in generated `static/js/emoji-shortcodes.js` (regenerate with `devplace emoji-sync` after a dependency bump, never hand-edit). YouTube embeds follow the single `devplacepy/embeds.py` spec only (validated ids, never substring matching, never another regex); the JS constants come from generated `static/js/embed-spec.js` (`devplace embeds-sync`, never hand-edit). Emails are masked in rendered text nodes only (never before mistune, or `*` parses as emphasis); `molodetz.nl` addresses stay verbatim. Em dashes become hyphens before mistune inside the cached render, so there is no per-template cost.
## Avatar seed choke point
The per-user avatar seed is the nullable `users.avatar_seed` column, falling back to the username. Always resolve it through the single null-safe choke point `avatar.avatar_seed(user)` (a Jinja global), never read `avatar_seed` or pass `username` to `avatar_url(...)` directly. Every render site (`_avatar_link.html`, `og_image`, the devRant avatar payload) goes through it. Regenerate is owner-or-admin at `POST /profile/{username}/regenerate-avatar` (fresh `generate_uid()`, cache invalidate, audit `profile.avatar.regenerate`); the old seed is never stored, so the old avatar cannot return. Devii tool `regenerate_avatar` (`CONFIRM_REQUIRED`).
+1 -1
View File
@@ -1,6 +1,6 @@
[project]
name = "devplacepy"
version = "1.1.17"
version = "1.1.19"
description = "DevPlace - The Developer Social Network"
requires-python = ">=3.12"
dependencies = [
+11
View File
@@ -159,3 +159,14 @@ The rule generalizes: if the production function reads a random-ish input or a t
| Admin page heading assertion fails | Admin pages use `<h2>` inside `.admin-toolbar`, not `<h1>` - assert `text=` or `.admin-toolbar h2:has-text(...)` |
| `test_auth_matrix` reports `422` instead of `401`/`403` | A POST route's form params are undocumented in `docs_api.py`, so the matrix sends an empty body and FastAPI validation (422) fires before the auth guard. Document every required form param so auth is reached and tested |
| `test_auth_matrix` reports `503` on a gateway endpoint | A prior test left the `openai` service stopped. Restore it in `finally` (see "Global `site_settings` tests -> Service enabled/disabled state") |
## Rigorous correctness verification (money, state machines, concurrency)
The persisted suite is example-based and blind to three bug classes: a formula wrong at an untried input, an invariant violated only after a long action sequence, and a race only two near-simultaneous requests trigger. Any feature touching a spendable resource (coins, credits, quotas), a bounded state machine (levels, tiers, counters with a floor/ceiling), or a read-then-write mutation reachable from more than one worker applies this procedure in addition to, not instead of, the persisted tests. Worked example with every bug it caught: Code Farm economy rebalance (`devplacepy/services/game/CLAUDE.md`).
Four escalating layers, in order, as disposable scripts calling the real functions against a temp DB (not pytest files unless separately requested):
1. **Property checks** on every pure formula over the full input domain (monotonicity, bounds, non-negativity, idempotency, additivity over a partition), iterating the real range (hundreds to thousands of values), not hand-picked spot checks.
2. **Stateful fuzzing.** Many entities, long randomized action sequences, invariants re-checked after every action (balances never negative, monotonic counters never decrease, bounds never exceeded). Catch the expected exception type and continue; this proves safety, not liveness.
3. **Concurrency with real separate OS processes, never threads.** Fresh production-representative state, never pre-seeded columns (NULL is not 0 in SQL, use `COALESCE`). Assert the exact right number of wins and hand-computed final totals. Fix races with one atomic conditional SQL statement at the chokepoint (`UPDATE ... WHERE <precondition>`, real driver `rowcount`), never a client-side lock.
4. **Static analysis** beyond `py_compile`: `pyflakes`/`ruff check` on every touched file (catches missing function-level imports invisible to other checks).