openvibers/openvibe.blog AGENTS.md

AGENTS.md

main 9.4 KB · 158 lines · markdown

Raw HistoryBlame Repository
1# AGENTS.md — OpenVibe.Blog
2
3## Project overview
4
5The official OpenVibe blog (`openvibe.blog/`) and a blog for every member: drafts, immutable
6revisions, series, tags and nested categories, scheduling, feeds, comments and AI writing desks. It
7uses the shared publishing packages (ADR-019) rather than its own copies. Node.js/Express,
8PostgreSQL (`ov_blog`), server-rendered, CommonJS, **no build step**.
9
10- Service id `blog`, port `4810`, origin `https://openvibe.blog`, unit `openvibe-blog.service`,
11 release root `/opt/openvibe.blog`.
12- Charter tables are in Blog's database ([migrations/](migrations/)); the publishing packages own the
13 revision, schedule, taxonomy, citation, media, discussion and SEO state behind `blog_`-prefixed
14 tables and three views that keep the charter names readable without a second copy.
15
16## What it owns
17
18- `blogs` (the official blog and one per member), `blog_memberships` (owner, editor, author),
19 `blog_posts`, `blog_series`, `blog_feed_settings`; revision/schedule/taxonomy/redirect state comes
20 from `openvibe-publishing` with the `blog` prefix.
21- Publishing state: draft → published revision; publish, unpublish, soft delete (`410 Gone`),
22 scheduled publish/unpublish (idempotent across worker restarts, leases, `blog.schedule.failed`).
23- Canonical URLs, RSS/Atom/JSON Feed, sitemap, robots, `llms.txt`, Search documents and IndexNow.
24- Members-only posts through OpenVibe.VIP (teaser + join link for everyone else).
25- The network changelog: Patch notes **drafts** on the official blog, for a person to review and
26 publish; the AI devblog desk (`server/devblog/`), patch-notes story selection and images.
27- Comments are Community threads referenced, never copied.
28
29Not owned: identity, the AI run engine, Media objects, VIP membership decisions, Search's index,
30Community's threads, Events' delivery.
31
32## Who calls it, and whom it calls
33
34- Callers: people in the browser; Network and other services with a Network service token audience
35 `openvibe.blog` and the route's capability; an `X-OV-Subject` membership header for on-behalf calls.
36- Depends on: Network (SSO client `blog`, JWKS, `identity.subject.resolve`), Community
37 (`community.comment.write`, optionally moderate), Media (`media.object.read`, namespace `blog`),
38 AI (`blog.draft_post`, drafts only), VIP (`vip.resource.policy.evaluate`, default
39 `http://127.0.0.1:4620`), Events (SDK outbox), Search (consumes `blog.index_document.*`),
40 `openvibe-publishing` and the pinned SDK/Shared/Contracts tarballs.
41- Without VIP, the members-only gate **fails closed**: the teaser and join link, never the body.
42
43## Repository map
44
45- **Entry:** [server/index.js](server/index.js) — app, worker (scheduled publication, media
46 verification), outbox, changelog and desks; graceful shutdown.
47- **App:** [server/app.js](server/app.js) — helmet/CSP, cookies, `/auth`, `/shared`, `/api/v1`,
48 `/write`, pages, editor, discovery, actor limits, account-data events.
49- **Config:** [server/config.js](server/config.js); database [server/db.js](server/db.js).
50- **Domain:** [server/domain/](server/domain/) — `blogs.js`, `publication.js`, `posts.js`,
51 `access.js`, `reading.js`, `effects.js`, `ai-drafts.js`, `account-data.js`.
52- **HTTP:** [server/http/](server/http/) — `public.js`, `editor.js`, `api.js`, `discovery.js`,
53 `openapi.js`, `actor-limits.js`, `errors.js`.
54- **Clients:** [server/clients/](server/clients/) — `network.js`, `community.js`, `media.js`,
55 `vip.js`.
56- **Auth/viewer:** [server/auth/viewer.js](server/auth/viewer.js), [server/auth/capabilities.js](server/auth/capabilities.js).
57- **Render:** [server/render/](server/render/) — `blocks.js`, `editor.js`, `home.js`, `layout.js`,
58 `pages.js`, `short.js`.
59- **Patch notes/AI desks:** [server/patch-notes/](server/patch-notes/), [server/devblog/](server/devblog/).
60- **Browser:** [public/js/blog-index.js](public/js/blog-index.js), [public/js/blog-editor.js](public/js/blog-editor.js),
61 [public/css/blog.css](public/css/blog.css).
62- **Deploy:** [deploy/systemd/openvibe-blog.service](deploy/systemd/openvibe-blog.service),
63 [deploy/nginx/openvibe.blog.conf](deploy/nginx/openvibe.blog.conf).
64
65## Commands
66
67```bash
68npm ci
69cp .env.example .env # OV_OAUTH_CLIENT_SECRET, BLOG_OFFICIAL_OWNERS, BLOG_FORM_SECRET, EVENTS_URL, BASE_URL
70npm run dev # http://localhost:4810
71npm run seed # the seed post (stays a draft until a person reviews it)
72npm test # test/run.js, PGlite, mock Network/Community/Media/Events
73npm run test:pg # same suite on PostgreSQL
74npm test -- schedule # filter by file name
75ov test # the harness's sharded run of what the change reaches
76node --check <file.js>
77```
78
79## Database and migrations
80
81PostgreSQL database `ov_blog` on the host's data role (ADR-035); development and tests use PGlite.
82Async reads/writes through `openvibe-sdk/db`. Migrations are `migrations/NNNN_*.sql`, applied at
83boot; never edit one that has run — add a new number. Revision rows are **immutable** (triggers abort
84UPDATE/DELETE); drafts live in `blog_post_drafts`, and a published post keeps showing its published
85revision while newer ones are drafted. A stale edit is `412 revision.conflict`, never lost work.
86Nothing is created at runtime.
87
88## Auth
89
90People sign in through Network SSO (OAuth client `blog`, callback `/auth/callback`) and get the
91viewer/session in [server/auth/viewer.js](server/auth/viewer.js). Memberships (`owner`, `editor`,
92`author`) gate the editor and API. Service callers need a Network service token with the
93capability from the pinned contracts release; `X-OV-Subject` scopes a call to a member. The official
94blog's owners come from `BLOG_OFFICIAL_OWNERS`, and Network admins act as its owners. Forms need
95`BLOG_FORM_SECRET`; a form token failure refuses the write.
96
97## Frontend loading model
98
99Server-rendered HTML and **plain forms** work without JavaScript: write, edit, publish, comment and
100configure ([test/nojs-editor.test.js](test/nojs-editor.test.js)). Two page scripts enhance the index
101and the editor; there is no SPA, no bundler and no build. `openvibe-shared` supplies the Frame and
102theme presets; `/shared/*` is served from the pinned package. CSP lives in
103[server/app.js](server/app.js) — add an origin there before loading from it. Public pages must stay
104cache-safe: no members-only or private text through cache headers, feeds, sitemap, Search or API.
105
106## Deploy
107
108`sudo ovhost deploy blog` (strategy `git-checkout`): fetch, fast-forward `/opt/openvibe.blog`,
109install on a lockfile change, restart, wait for `/api/ready`, roll back on failure. Unit
110`openvibe-blog.service` on `127.0.0.1:4810`, env `/etc/openvibe/blog.env` (0600); the release
111migrates `ov_blog` at boot. `sudo ovhost rollback blog --to <sha>`; the schema only adds tables and
112columns, so a rollback is safe. The vhost is
113[deploy/nginx/openvibe.blog.conf](deploy/nginx/openvibe.blog.conf). No secret in a command line,
114file or log.
115
116## Tests
117
118`npm test` runs each `test/*.test.js` in its own process through `openvibe-shared/test-runner`
119(60 s/file), with PGlite and in-process Network/Community/Media/Events mocks. The README's
120"Acceptance" table maps each guarantee to its test: scheduling idempotency and failures, immutable
121revisions and 412, feeds/canonical/Search convergence, slug 301s, VIP privacy across pages/JSON/
122feeds/sitemap/Search, broken Media assets vs outage, no-JS editing, capabilities, the seed and
123discovery files, and contracts. `ov test` runs the same.
124
125## Conventions
126
127- CommonJS, 4-space indent, single quotes, semicolons; domain logic in `server/domain/`, HTTP in
128 `server/http/`, no SQL in routes.
129- Reuse `openvibe-publishing` for revisions/schedule/taxonomy/citations/media/discussion/seo; do not
130 reimplement a publishing primitive.
131- IDs and errors from `openvibe-contracts`; `application/problem+json` with request ids.
132- Everything a reader can see is escaped; never interpolate raw Markdown or user HTML.
133- A visible change needs a test that a private post stays private.
134
135## Pitfalls
136
137- **AI drafts are drafts.** `blog.draft_post` output is never published by the model; a person
138 reviews and publishes. The seed post stays a draft for the same reason.
139- **VIP fails closed.** A VIP outage yields the teaser and join link, never the body; a cached "yes"
140 ends within its TTL and at once on `vip.membership.changed`.
141- **Revisions are immutable.** Revert is a new revision; do not UPDATE history.
142- **Unpublishing closes the share door:** an unpublish/delete must tombstone with a higher revision
143 and must not leave a public share row or Search document behind.
144- **Draft and members-only content must not leak** through feeds, sitemap, JSON, `.json` API, cache
145 headers or product events; `test/privacy.test.js` and `test/members-vip.test.js` enforce it.
146- **Slug changes leave 301s from every old path**, and chains collapse.
147- **No JavaScript must still work** in the editor and forms; do not move a required action into a
148 script.
149- **The changelog writes drafts**, not releases; Patch notes and the seed are reviewed by a person.
150- **Community threads are referenced, never copied** into the post body.
151
152## Documentation
153
154- [README.md](README.md) — features, routes, capabilities, acceptance, security and deploy.
155- [docs/devblog-writer.md](docs/devblog-writer.md) — the AI devblog desk.
156- [docs/service-manifest-proposal.json](docs/service-manifest-proposal.json), [docs/capabilities-proposal/](docs/capabilities-proposal/).
157- The shared publishing contracts are in OpenVibe.Contracts (`publishing.*`, `blog.*`).
158