domma-cms 0.91.1 → 0.92.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "domma-cms",
-  "version": "0.91.1",
+  "version": "0.92.0",
   "description": "File-based CMS powered by Domma and Fastify. Run npx domma-cms my-site to create a new project.",
   "type": "module",
   "main": "server/server.js",

package/plugins/feedback/CLAUDE.md

@@ -0,0 +1,96 @@
+# feedback - AI Assistant Guide
+
+## Purpose
+
+Site admins tell Domma (the vendor) what is broken, missing or good, from their own admin, and see
+what became of it. Free tier: it ships in the CMS (synced by `make sync-free-tier`).
+
+ONE plugin, TWO sides, chosen at registration by where it runs:
+
+- **sender** - any site the manager started (it has `MANAGER_URL` + `FLEET_TOKEN` in its environment,
+  set by site-manager's processManager). The screen is "Send feedback" plus this site's reports.
+- **receiver** - the manager (dcm). Detected by `plugins/site-manager/services/fleetTokens.js` existing
+  beside this plugin (`lib/receiver.js isManager()`). The screen is the inbox of every site's reports.
+
+A site the manager did not start (a standalone install) has nowhere to send to: the screen says so,
+`POST /send` answers 409.
+
+## Files
+
+- `plugin.js` - both route sets; which one registers is decided once at boot (`options.mode` overrides in tests)
+- `lib/shape.js` - PURE: types, severities, statuses, `cleanSubmission`, `buildPayload`, `receivedReport`,
+  `senderView` (the whitelist), `cleanUpdate`, `statusFromIssue`, `createThrottle`, `issueDescription`
+- `lib/sender.js` - the outbox (`data/outbox.json`), `managerApi` (fetch, injectable), `flush`, `mergeReports`
+- `lib/receiver.js` - the `feedback-reports` collection, token -> slug, site names, patches with history
+- `collections/feedback-reports.json` - schema, created by `ensureCollection()` on the manager only
+- `admin/views/feedback.js` - the shell: asks `/mode`, loads `send.js` or `inbox.js`
+- `admin/lib/kit.js`, `admin/templates/feedback.html`, `admin/css/index.css`
+- `tests/shape.test.js` (pure), `tests/api.test.js` (a sender app wired into a receiver app via inject)
+
+## Routes (`/api/plugins/feedback`)
+
+Sender (permission `feedback` action `send`):
+
+| Method | Path | Purpose |
+|---|---|---|
+| GET | `/mode` | `{mode:'sender', connected, site}` |
+| GET | `/meta` | types, statuses, severities |
+| GET | `/count` | sidebar badge: replies not yet opened (from the outbox copy - never calls the manager) |
+| GET | `/sent` | sends anything waiting, then the manager's `/fleet/mine` merged with the outbox |
+| POST | `/send` | a report: written to the outbox FIRST, then sent; answers `state: sent|waiting` |
+| PUT | `/sent/:id/seen` | `{replyAt}` - this reply has been read |
+
+Receiver (inbox routes: permission `feedback` action `manage`):
+
+| Method | Path | Purpose |
+|---|---|---|
+| POST | `/fleet/submit` | a site's report. **No session**: `Authorization: Bearer <fleet token>` names the site. bodyLimit 32 KB, per-site throttle |
+| GET | `/fleet/mine` | that site's reports, `senderView()` fields only |
+| GET | `/mode` | `{mode:'receiver', waypoint}` |
+| GET | `/count` | badge: status `new` (danger tone if any is a blocker) |
+| GET | `/reports` · `/reports/:id` | the inbox; reading one freshens its Waypoint status |
+| PUT | `/reports/:id` | `{status?, reply?, notes?}` |
+| DELETE | `/reports/:id` | gone for the site too |
+| GET | `/waypoint` | `{available, projects}` |
+| POST | `/reports/:id/promote` | `{projectId, type, priority}` -> a Waypoint issue; 503 without Waypoint, 409 if already linked |
+
+## Storage
+
+- Manager: collection `feedback-reports` (file adapter), NOT `feedback` - that slug is the starter preset
+  every site has for visitor comments. All four API verbs are OFF (a collection's default is a PUBLIC
+  read, and these carry admins' names and emails). Record: site, ref, type, title, description, where,
+  severity, cmsVersion, userId/userName/userEmail, status, reply, replyAt, notes, issueId, issueKey,
+  issueStatus, history[].
+- Site: `data/outbox.json` - `{items: [{ref, state: waiting|sent|refused, payload, remoteId, reply, replyAt,
+  lastError}], seen: {reportId: replyAt}}`. The engine updater preserves plugin `data/`.
+
+## Waypoint Pro integration (feature-detected both ways; neither imports the other)
+
+- Waypoint sets `globalThis.dommaWaypoint = {version: 1, listProjects(), createIssue({projectId, title,
+  description, type, priority, reporterName, source: {plugin: 'feedback', id, site, url}}), getIssue(idOrKey)}`.
+- Feedback (receiver) sets `globalThis.dommaFeedback = {version: 1, issueUpdated({sourceId, issue: {id, key,
+  statusName, statusCategory}})}`. Waypoint calls it when a linked issue moves.
+- `statusFromIssue`: todo -> planned, doing -> in-progress, done -> done; a report set to `declined`
+  (shown "Not planned") by hand keeps it.
+- The inbox offers issue types bug/story/task and priorities highest..lowest as plain strings.
+
+## Gotchas
+
+- **Who sent it is never the browser's word.** The sender builds the payload from `request.user`; the
+  manager attributes a report to the slug the fleet TOKEN resolves to and ignores any `site` in the body.
+  A site can still vouch for any of its own admins - it cannot speak for another site.
+- **Tokens rotate whenever either end restarts** (fleetTokens.js is memory-only), so a send can meet a
+  401 or ECONNREFUSED for a few seconds. That is why the outbox exists: a report is "sent or waiting",
+  never lost. Waiting ones go on the next `/sent` and on the timer (`syncMinutes`, default 60, which also
+  notices new replies and raises a `feedback:reply` notification). A retry carries the same `ref`, and the
+  manager answers the existing report (200) instead of making a second.
+- **The global rate limiter exempts loopback**, which is where every site calls from, so `/fleet/submit`
+  has its own per-site throttle (`perSiteMax` in `perSiteMinutes`, default 10 in 10). A deduplicated
+  retry counts too.
+- **Help popovers are wired BEFORE the row template goes in.** `helpPopovers()` scans icons; a template
+  scanned while its icon is still `{{icon}}` is marked `data-icon-processed`, every row cloned from it
+  inherits the mark and stays blank. Rows are rescanned (after `M.flush()`) whenever they change.
+- **`[hidden]` needs its own rule.** `data-bind-hidden` sets the attribute, and any `display` rule
+  (`.fb-note` is flex) beats the browser's. `index.css` carries `.fb [hidden] {display: none !important}`.
+- Only this machine's sites can reach dcm (the fleet token lives in this manager's memory). Sites on other
+  machines would need their own manager to relay with an installation key; not built.

package/plugins/feedback/admin/css/index.css

@@ -0,0 +1,80 @@
+/* Feedback - admin styles. Theme tokens only (every one below is defined by every Domma theme). */
+
+/* data-bind-hidden sets [hidden]; any display rule below would otherwise beat it. */
+.fb [hidden], .fb-detail [hidden], .fb-form [hidden] { display: none !important; }
+
+.fb { max-width: 60rem; }
+.fb-card { background: var(--dm-surface); border: 1px solid var(--dm-border); border-radius: var(--dm-radius-lg); padding: 1rem 1.1rem; }
+.fb-bar { display: flex; align-items: center; gap: .6rem; flex-wrap: wrap; margin-bottom: .8rem; }
+.fb-spacer { flex: 1; }
+.fb-intro { display: flex; flex-direction: column; gap: .15rem; }
+.fb-intro span { color: var(--dm-text-secondary); font-size: var(--dm-font-size-sm); }
+
+.fb-note { margin: .5rem 0; color: var(--dm-text-secondary); font-size: var(--dm-font-size-sm); display: flex; align-items: center; gap: .4rem; flex-wrap: wrap; }
+.fb-note.is-bad { color: var(--dm-danger); }
+.fb-note.is-warn { color: var(--dm-text); background: color-mix(in srgb, var(--dm-warning) 14%, transparent); border-radius: var(--dm-radius-md); padding: .45rem .7rem; }
+.fb-hint { margin: .2rem 0 0; color: var(--dm-text-secondary); font-size: var(--dm-font-size-xs); }
+
+.fb-empty-state { text-align: center; padding: 2.5rem 1rem; color: var(--dm-text-secondary); }
+.fb-empty-state h3 { margin: .6rem 0 .4rem; color: var(--dm-text); }
+.fb-empty-state p { max-width: 34rem; margin: 0 auto; }
+
+/* The status chips and filters */
+.fb-seg { display: inline-flex; flex-wrap: wrap; gap: .25rem; }
+.fb-seg button { border: 1px solid var(--dm-border); background: none; color: var(--dm-text-secondary); border-radius: var(--dm-radius-full);
+  padding: .2rem .7rem; font-size: var(--dm-font-size-sm); cursor: pointer; }
+.fb-seg button b { font-weight: 600; margin-left: .2rem; }
+.fb-seg button.is-on { background: var(--dm-primary-light); color: var(--dm-text); border-color: var(--dm-primary); }
+.fb-filter { width: auto; min-width: 10rem; }
+.fb-search { flex: 1; min-width: 12rem; }
+
+/* Rows */
+.fb-list { display: flex; flex-direction: column; }
+.fb-row { display: flex; align-items: center; gap: .75rem; padding: .6rem .5rem; border-top: 1px solid var(--dm-border); cursor: pointer; border-radius: var(--dm-radius-md); }
+.fb-row:first-child { border-top: 0; }
+.fb-row:hover, .fb-row:focus-visible { background: var(--dm-hover-bg); outline: none; }
+.fb-type { display: inline-flex; color: var(--dm-text-secondary); }
+.fb-main { flex: 1; min-width: 0; display: flex; flex-direction: column; }
+.fb-main strong { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.fb-main small { color: var(--dm-text-secondary); font-size: var(--dm-font-size-xs); }
+.fb-key { font-family: var(--dm-font-mono, monospace); font-size: var(--dm-font-size-xs); color: var(--dm-text-secondary); }
+.fb-dot { width: .55rem; height: .55rem; border-radius: 50%; background: var(--dm-primary); flex: none; }
+.fb-kebab { border: 0; background: none; color: var(--dm-text-secondary); cursor: pointer; font-size: 1.1rem; padding: 0 .35rem; border-radius: var(--dm-radius-md); }
+.fb-kebab:hover { background: var(--dm-hover-bg); color: var(--dm-text); }
+
+.fb-chip { font-size: var(--dm-font-size-xs); font-weight: 600; padding: .12rem .55rem; border-radius: var(--dm-radius-full); white-space: nowrap;
+  background: color-mix(in srgb, var(--dm-text-secondary) 14%, transparent); color: var(--dm-text); }
+.fb-chip.is-info { background: color-mix(in srgb, var(--dm-info) 18%, transparent); }
+.fb-chip.is-warning { background: color-mix(in srgb, var(--dm-warning) 22%, transparent); }
+.fb-chip.is-success { background: color-mix(in srgb, var(--dm-success) 20%, transparent); }
+.fb-chip.is-bad { background: color-mix(in srgb, var(--dm-danger) 20%, transparent); }
+
+/* Forms and panels */
+.fb-form { display: flex; flex-direction: column; gap: .35rem; }
+.fb-form .form-label { margin-top: .5rem; }
+.fb-types { display: grid; grid-template-columns: repeat(auto-fill, minmax(10rem, 1fr)); gap: .4rem; }
+.fb-types button { display: flex; align-items: center; gap: .45rem; border: 1px solid var(--dm-border); background: none; color: var(--dm-text);
+  border-radius: var(--dm-radius-md); padding: .5rem .6rem; cursor: pointer; text-align: left; font-size: var(--dm-font-size-sm); }
+.fb-types button:hover { background: var(--dm-hover-bg); }
+.fb-types button.is-on { border-color: var(--dm-primary); background: var(--dm-primary-light); }
+.fb-actions { display: flex; gap: .5rem; align-items: center; margin-top: .8rem; }
+
+.fb-detail h4 { margin: 1.2rem 0 .4rem; display: flex; align-items: center; gap: .4rem; }
+.fb-detail h4 small { color: var(--dm-text-secondary); font-weight: 400; }
+.fb-facts { display: grid; grid-template-columns: repeat(auto-fill, minmax(14rem, 1fr)); gap: .5rem 1rem; margin: 0; }
+.fb-facts dt { color: var(--dm-text-secondary); font-size: var(--dm-font-size-xs); }
+.fb-facts dd { margin: 0; overflow-wrap: anywhere; }
+.fb-text { white-space: pre-wrap; overflow-wrap: anywhere; background: var(--dm-background); border: 1px solid var(--dm-border);
+  border-radius: var(--dm-radius-md); padding: .7rem .8rem; }
+.fb-reply { border-color: var(--dm-primary); }
+.fb-waypoint { margin-top: 1rem; padding: .7rem .8rem; border: 1px dashed var(--dm-border); border-radius: var(--dm-radius-md); }
+.fb-waypoint h4 { margin-top: 0; }
+.fb-grid3 { display: grid; grid-template-columns: repeat(3, minmax(0, 1fr)); gap: .6rem; }
+.fb-history { list-style: none; margin: 0; padding: 0; font-size: var(--dm-font-size-sm); }
+.fb-history li { display: flex; justify-content: space-between; gap: 1rem; padding: .3rem 0; border-top: 1px solid var(--dm-border); }
+.fb-history small { color: var(--dm-text-secondary); }
+
+@media (max-width: 640px) {
+  .fb-grid3 { grid-template-columns: 1fr; }
+  .fb-row { flex-wrap: wrap; }
+}

package/plugins/feedback/admin/lib/kit.js

@@ -0,0 +1,105 @@
+/**
+ * Feedback admin - what both screens share: the admin's helpers (loaded at run
+ * time; a plugin never imports admin/ statically - the updater replaces it),
+ * the API, escaping, dates and slideovers.
+ *
+ * @module feedback/admin/lib/kit
+ */
+
+export const SIDEBAR_URL = '#/plugins/feedback';
+export const BASE = '/api/plugins/feedback';
+
+let kit = null;
+
+/** tool-kit, plugin-chrome and help-popover, once, with stand-ins for an older admin. */
+export function loadKit() {
+    if (!kit) {
+        kit = Promise.all([
+            import('/admin/js/lib/tool-kit.js').catch(() => ({})),
+            import('/admin/js/lib/plugin-chrome.js').catch(() => ({})),
+            import('/admin/js/lib/help-popover.js').catch(() => ({}))
+        ]).then(([tk, chrome, help]) => ({
+            onceClosed: tk.onceClosed || ((so, fn) => { const c = so.close.bind(so); so.close = (...a) => { const r = c(...a); fn?.(); return r; }; }),
+            openMenuAt: tk.openMenuAt || ((el) => {
+                const r = el.getBoundingClientRect();
+                el.dispatchEvent(new MouseEvent('contextmenu', {bubbles: true, cancelable: true, clientX: r.left, clientY: r.bottom, view: window}));
+            }),
+            viewLifetime: tk.viewLifetime || (() => ({add() {}, reset() {}})),
+            addBannerAction: chrome.addBannerAction || (() => null),
+            helpPopovers: help.helpPopovers || (() => () => {})
+        }));
+    }
+    return kit;
+}
+
+const seg = (id) => encodeURIComponent(String(id));
+export const api = {
+    mode: () => H.get(`${BASE}/mode`),
+    meta: () => H.get(`${BASE}/meta`),
+    sent: () => H.get(`${BASE}/sent`),
+    send: (d) => H.post(`${BASE}/send`, d),
+    seen: (id, replyAt) => H.put(`${BASE}/sent/${seg(id)}/seen`, {replyAt}),
+    reports: () => H.get(`${BASE}/reports`),
+    report: (id) => H.get(`${BASE}/reports/${seg(id)}`),
+    update: (id, d) => H.put(`${BASE}/reports/${seg(id)}`, d),
+    remove: (id) => H.delete(`${BASE}/reports/${seg(id)}`),
+    waypoint: () => H.get(`${BASE}/waypoint`),
+    promote: (id, d) => H.post(`${BASE}/reports/${seg(id)}/promote`, d)
+};
+
+/** E.confirm and slideover titles render HTML: user text goes in escaped. */
+export const esc = (s) => String(s ?? '').replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+
+/** A small DOM tree from an HTML string that holds NO unescaped user data. */
+export function fragment(html) {
+    const t = document.createElement('template');
+    t.innerHTML = html.trim();
+    return t.content.firstElementChild;
+}
+
+export const store = {
+    get(k) { try { return S.get(k); } catch { return null; } },
+    set(k, v) { try { S.set(k, v); } catch { /* a convenience */ } }
+};
+
+/** The sidebar re-asks the Feedback badge. */
+export function refreshBadge() {
+    try { window.dispatchEvent(new CustomEvent('dm:sidebar-count', {detail: {url: SIDEBAR_URL}})); } catch { /* no sidebar */ }
+}
+
+/** "3 min ago", "26 Sep". */
+export function when(iso) {
+    const t = new Date(iso).getTime();
+    if (!Number.isFinite(t)) return '';
+    const s = (Date.now() - t) / 1000;
+    if (s < 60) return 'just now';
+    if (s < 3600) return `${Math.round(s / 60)} min ago`;
+    if (s < 86400) return `${Math.round(s / 3600)} h ago`;
+    if (s < 86400 * 6) return `${Math.round(s / 86400)} d ago`;
+    return new Date(t).toLocaleDateString(undefined, {day: 'numeric', month: 'short', ...(s > 86400 * 300 ? {year: 'numeric'} : {})});
+}
+
+/** Full date and time, for a detail panel. */
+export const stamp = (iso) => {
+    const t = new Date(iso);
+    return Number.isFinite(t.getTime()) ? t.toLocaleString(undefined, {dateStyle: 'medium', timeStyle: 'short'}) : '';
+};
+
+/**
+ * A slideover holding `html`, bound to `model`. Everything is disposed and the
+ * element removed on close.
+ *
+ * @returns {Promise<{so, panel, close: () => void}>}
+ */
+export async function openPanel({title, size = 'md', html, model = {}, methods = {}, cleanup = () => {}}) {
+    const {onceClosed, helpPopovers} = await loadKit();
+    const so = E.slideover({title: esc(title), size, position: 'right'});
+    const panel = fragment(html);
+    so.element.appendChild(panel);
+    const disposeHelp = helpPopovers(panel, {position: 'bottom'});
+    const handle = M.applyBindings(model, panel, {methods});
+    onceClosed(so, () => { cleanup(); handle.dispose(); disposeHelp(); });
+    I.scan(panel);
+    so.open();
+    return {so, panel, close: () => so.close()};
+}

package/plugins/feedback/admin/templates/feedback.html

@@ -0,0 +1 @@
+<div class="fb" data-feedback-admin></div>

package/plugins/feedback/admin/views/feedback.js

@@ -0,0 +1,63 @@
+/**
+ * Feedback - one sidebar entry, two screens, decided by the server:
+ *
+ *   on a site     Send feedback, and what this site has sent (send.js)
+ *   on the manager  the inbox of every site's feedback (inbox.js)
+ *
+ *   #/plugins/feedback        the screen
+ *   #/plugins/feedback/<id>   the same, with that report open (a notification's link)
+ *
+ * Path segments, not ?query: the admin router 404s a query on a fresh load.
+ */
+
+import {api, loadKit} from '../lib/kit.js';
+
+const ROUTE = /^#\/plugins\/feedback(\/|$)/;
+const V = '1.0.0';
+let lifetime = null;
+
+export const feedbackView = {
+    templateUrl: '/plugins/feedback/admin/templates/feedback.html',
+
+    async onMount($container) {
+        const kit = await loadKit();
+        lifetime ??= kit.viewLifetime(ROUTE);
+        if (!ROUTE.test(location.hash)) return;
+        lifetime.reset();
+        const scope = (fn) => { lifetime.add(fn); return fn; };
+        const container = $container.get(0);
+        const root = container.querySelector('[data-feedback-admin]') || container;
+        const mountedFor = location.hash;
+        const here = () => location.hash === mountedFor && root.isConnected;
+        const m = location.hash.match(/^#\/plugins\/feedback\/([^/?#]+)/);
+        const id = m ? decodeURIComponent(m[1]) : '';
+
+        const fail = (text) => {
+            root.innerHTML = '';
+            const p = document.createElement('p');
+            p.className = 'fb-note is-bad';
+            p.textContent = text;
+            root.appendChild(p);
+        };
+
+        let mode;
+        let meta;
+        try {
+            [mode, meta] = await Promise.all([api.mode(), api.meta()]);
+        } catch (err) {
+            fail(`Feedback could not load: ${err.message || err}`);
+            return;
+        }
+        if (!here()) return;
+
+        const screen = mode.mode === 'receiver' ? 'inbox' : 'send';
+        try {
+            const mod = await import(`/plugins/feedback/admin/views/${screen}.js?v=${V}`);
+            if (!here()) return;
+            const cleanup = await mod.mount(root, {kit, scope, here, container, $container, mode, meta, id});
+            if (typeof cleanup === 'function') scope(cleanup);
+        } catch (err) {
+            fail(`This screen could not load: ${err.message || err}`);
+        }
+    }
+};