domma-cms 0.91.1 → 0.92.1

package/plugins/feedback/plugin.js

@@ -0,0 +1,276 @@
+/**
+ * Feedback - site admins tell Domma what is broken, missing or good, and see
+ * what became of it. Mounted at /api/plugins/feedback.
+ *
+ * ONE plugin, TWO sides, chosen by where it runs:
+ *
+ *   sender   (any site the manager started: MANAGER_URL + FLEET_TOKEN)
+ *     GET  /mode                  which side, and whether this site is connected
+ *     GET  /count                 sidebar badge: replies not yet read
+ *     GET  /sent                  this site's reports (sends any waiting first)
+ *     POST /send                  a new report: kept here, then sent
+ *     PUT  /sent/:id/seen         a reply has been read
+ *
+ *   receiver (the manager - Site Manager is installed beside it)
+ *     POST /fleet/submit          a site's report (Bearer fleet token)
+ *     GET  /fleet/mine            that site's reports, sender-safe fields only
+ *     GET  /mode · GET /count     'new' reports
+ *     GET  /reports · GET /reports/:id · PUT /reports/:id · DELETE /reports/:id
+ *     GET  /waypoint              is Waypoint Pro here, and its projects
+ *     POST /reports/:id/promote   make a Waypoint issue from a report
+ *
+ * Nothing the browser sends says who sent a report or which site it came from:
+ * the user is the session's, the site is the one the fleet token names.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import {fileURLToPath} from 'node:url';
+import defaults from './config.js';
+import {
+    SEVERITIES, STATUSES, TYPES, buildPayload, cleanSubmission, cleanUpdate, createThrottle, issueDescription, senderView
+} from './lib/shape.js';
+import {createOutbox, flush, managerApi, managerOf, mergeReports, newRef} from './lib/sender.js';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const NAME = 'feedback';
+
+/** The CMS this site runs, from the updater's marker (the site's package.json is the SITE's version). */
+function cmsVersion() {
+    for (const f of [path.join(process.cwd(), '.domma'), path.join(process.cwd(), '.cmsVersion')]) {
+        try {
+            const raw = fs.readFileSync(f, 'utf8');
+            try { return String(JSON.parse(raw).cmsVersion || ''); } catch { return raw.trim(); }
+        } catch { /* try the next */ }
+    }
+    try { return JSON.parse(fs.readFileSync(path.join(process.cwd(), 'package.json'), 'utf8')).version || ''; } catch { return ''; }
+}
+
+export default async function feedbackPlugin(fastify, options) {
+    const {authenticate, requirePermission} = options.auth;
+    const hooks = options.hooks || {};
+    const can = (action) => ({preHandler: [authenticate, requirePermission(NAME, action)]});
+    const settings = {...defaults, ...(options.settings || {})};
+    const receiverMod = await import('./lib/receiver.js');
+    const mode = options.mode || (receiverMod.isManager() ? 'receiver' : 'sender');
+    const notifyOk = typeof hooks.notify === 'function';
+    if (typeof hooks.registerNotificationSource === 'function') {
+        try {
+            if (mode === 'receiver') {
+                hooks.registerNotificationSource({id: 'new-report', label: 'New feedback from a site',
+                    description: 'A site admin sent a bug, request or question.', severity: 'info', audience: 'admins'});
+            } else {
+                hooks.registerNotificationSource({id: 'reply', label: 'Domma replied to your feedback',
+                    description: 'Domma answered something this site sent.', severity: 'info', audience: 'admins'});
+            }
+        } catch (err) { fastify.log.warn(`[feedback] notification source: ${err.message}`); }
+    }
+
+    fastify.get('/meta', can('send'), async () => ({types: TYPES, statuses: STATUSES, severities: SEVERITIES}));
+
+    if (mode === 'receiver') await receiverRoutes(fastify, {can, hooks, notifyOk, receiverMod, settings, options});
+    else await senderRoutes(fastify, {can, hooks, notifyOk, settings, options});
+}
+
+// ---------------------------------------------------------------------------------
+// Sender
+// ---------------------------------------------------------------------------------
+
+async function senderRoutes(fastify, {can, hooks, notifyOk, settings, options}) {
+    const env = options.env || process.env;
+    const manager = managerOf(env);
+    const outbox = createOutbox(options.dataDir || path.join(HERE, 'data'));
+    const api = manager ? managerApi(manager, options.fetch) : null;
+
+    /** Send what waits, then read the manager's view; tell admins about replies they have not heard of. */
+    async function sync() {
+        if (!api) return {reports: mergeReports(outbox.all(), null, outbox.seen()), reachable: false, error: ''};
+        const pushed = await flush(outbox, api);
+        const mine = await api.mine();
+        const remote = mine.ok ? (mine.body?.reports || []) : null;
+        const reports = mergeReports(outbox.all(), remote, outbox.seen());
+        // Keep the last-known reply on the outbox copy: the badge reads that, never the manager.
+        if (remote) for (const r of reports) if (!r.local && r.ref) outbox.mark(r.ref, {reply: r.reply ? '1' : '', replyAt: r.replyAt, remoteId: r.id});
+        if (remote && notifyOk) {
+            for (const r of reports.filter(x => x.unread)) {
+                hooks.notify({title: `Domma replied: ${r.title}`, body: r.reply.slice(0, 300), severity: 'info', source: 'reply',
+                    link: '#/plugins/feedback', dedupeKey: `feedback-reply:${r.id}:${r.replyAt}`});
+            }
+        }
+        return {reports, reachable: Boolean(remote), error: mine.ok ? pushed.error : mine.error};
+    }
+
+    // The hourly sync: waiting reports go, new replies are noticed. Off in tests.
+    if (api && options.timer !== false) {
+        const t = setInterval(() => { sync().catch(() => {}); }, Math.max(5, Number(settings.syncMinutes) || 60) * 60_000);
+        t.unref?.();
+        const first = setTimeout(() => { sync().catch(() => {}); }, 60_000);
+        first.unref?.();
+        fastify.addHook('onClose', async () => { clearInterval(t); clearTimeout(first); });
+    }
+
+    fastify.get('/mode', can('send'), async () => ({mode: 'sender', connected: Boolean(manager), site: manager?.slug || ''}));
+
+    fastify.get('/count', can('send'), async () => {
+        const seen = outbox.seen();
+        // From the last sync's copy: the badge must not call the manager every minute.
+        const unread = outbox.all().filter(i => i.reply && i.replyAt && seen[i.remoteId] !== i.replyAt);
+        const waiting = outbox.all().filter(i => i.state === 'waiting').length;
+        return {
+            count: unread.length,
+            label: unread.length ? `${unread.length} new ${unread.length === 1 ? 'reply' : 'replies'} from Domma` : '',
+            tone: 'info',
+            details: {title: 'Feedback', rows: [{label: 'New replies', value: String(unread.length)}, {label: 'Waiting to send', value: String(waiting)}],
+                items: unread.slice(0, 5).map(i => ({text: i.payload?.title || 'A report'})), empty: 'Nothing new from Domma.'}
+        };
+    });
+
+    fastify.get('/sent', can('send'), async () => {
+        const r = await sync();
+        return {connected: Boolean(manager), reachable: r.reachable, error: r.error, reports: r.reports};
+    });
+
+    fastify.post('/send', can('send'), async (request, reply) => {
+        if (!manager) return reply.code(409).send({error: 'This site is not connected to Domma, so feedback cannot be sent from here.'});
+        const {report, error} = cleanSubmission(request.body || {});
+        if (error) return reply.code(400).send({error});
+        const payload = buildPayload({report, user: request.user, cmsVersion: cmsVersion(), site: manager.slug, ref: newRef()});
+        outbox.add(payload);
+        const r = await flush(outbox, api);
+        const item = outbox.all().find(i => i.ref === payload.ref);
+        return reply.code(201).send({ref: payload.ref, state: item?.state || 'waiting',
+            message: item?.state === 'sent' ? 'Sent to Domma. Thank you.' : `Kept here and sent as soon as Domma answers. (${r.error || 'not sent yet'})`});
+    });
+
+    fastify.put('/sent/:id/seen', can('send'), async (request) => {
+        const {replyAt} = request.body || {};
+        outbox.markSeen(String(request.params.id), String(replyAt || ''));
+        return {ok: true};
+    });
+}
+
+// ---------------------------------------------------------------------------------
+// Receiver (the manager)
+// ---------------------------------------------------------------------------------
+
+async function receiverRoutes(fastify, {can, hooks, notifyOk, receiverMod, settings, options}) {
+    const rx = receiverMod;
+    const slugOf = options.slugFromToken || rx.slugFromToken;
+    const names = options.siteNames || rx.siteNames;
+    const allowed = createThrottle({max: Number(settings.perSiteMax) || 10, windowMs: (Number(settings.perSiteMinutes) || 10) * 60_000});
+    try { await rx.ensureCollection(); } catch (err) { fastify.log.error(`[feedback] collection: ${err.message}`); }
+
+    // Waypoint Pro, when it is loaded, calls this when a linked issue moves.
+    globalThis.dommaFeedback = {
+        version: 1,
+        async issueUpdated({sourceId, issue} = {}) {
+            try { await rx.issueMoved(String(sourceId || ''), issue || {}); } catch { /* the report went */ }
+        }
+    };
+    fastify.addHook('onClose', async () => { if (globalThis.dommaFeedback?.version === 1) delete globalThis.dommaFeedback; });
+
+    const waypoint = () => (globalThis.dommaWaypoint?.version === 1 ? globalThis.dommaWaypoint : null);
+
+    // ---- From the sites (no session: the fleet token IS the identity) ----
+
+    fastify.post('/fleet/submit', {bodyLimit: 32 * 1024}, async (request, reply) => {
+        const slug = await slugOf(request.headers.authorization);
+        if (!slug) return reply.code(401).send({error: 'Unknown site.'});
+        if (!allowed(slug)) return reply.code(429).send({error: 'That is a lot of feedback at once - try again in a few minutes.'});
+        const r = await rx.receive(slug, request.body || {});
+        if (r.error) return reply.code(400).send({error: r.error});
+        if (r.created && notifyOk) {
+            const d = r.entry.data;
+            hooks.notify({title: `Feedback from ${names()[slug] || slug}: ${d.title}`, body: d.description.slice(0, 300),
+                severity: d.severity === 'blocker' ? 'warning' : 'info', source: 'new-report',
+                link: `#/plugins/feedback/${r.entry.id}`, dedupeKey: `feedback:${r.entry.id}`});
+        }
+        return reply.code(r.created ? 201 : 200).send({id: r.entry.id, status: r.entry.data.status});
+    });
+
+    fastify.get('/fleet/mine', async (request, reply) => {
+        const slug = await slugOf(request.headers.authorization);
+        if (!slug) return reply.code(401).send({error: 'Unknown site.'});
+        return {reports: (await rx.reportsOf(slug)).map(senderView)};
+    });
+
+    // ---- The inbox ----
+
+    fastify.get('/mode', can('manage'), async () => ({mode: 'receiver', waypoint: Boolean(waypoint())}));
+
+    fastify.get('/count', can('manage'), async () => {
+        const fresh = (await rx.allReports()).filter(e => e.data?.status === 'new');
+        const n = names();
+        return {
+            count: fresh.length,
+            label: fresh.length ? `${fresh.length} new` : '',
+            tone: fresh.some(e => e.data?.severity === 'blocker') ? 'danger' : 'info',
+            details: {title: 'New feedback', items: fresh.slice(0, 6).map(e => ({text: e.data.title, meta: n[e.data.site] || e.data.site})),
+                empty: 'Nothing new.'}
+        };
+    });
+
+    fastify.get('/reports', can('manage'), async () => {
+        const n = names();
+        return {sites: n, reports: (await rx.allReports()).map(e => ({id: e.id, ...e.data, siteName: n[e.data.site] || e.data.site,
+            createdAt: e.meta?.createdAt, updatedAt: e.meta?.updatedAt}))};
+    });
+
+    fastify.get('/reports/:id', can('manage'), async (request, reply) => {
+        let e = await rx.getReport(request.params.id);
+        if (!e) return reply.code(404).send({error: 'No such report.'});
+        // Freshen the linked issue's status while we are here.
+        const wp = waypoint();
+        if (wp && e.data.issueId) {
+            try {
+                const issue = await wp.getIssue(e.data.issueId);
+                if (issue && issue.statusName !== e.data.issueStatus) e = (await rx.issueMoved(e.id, issue)) || e;
+            } catch { /* Waypoint could not say */ }
+        }
+        return {id: e.id, ...e.data, siteName: names()[e.data.site] || e.data.site, createdAt: e.meta?.createdAt, updatedAt: e.meta?.updatedAt};
+    });
+
+    fastify.put('/reports/:id', can('manage'), async (request, reply) => {
+        const e = await rx.getReport(request.params.id);
+        if (!e) return reply.code(404).send({error: 'No such report.'});
+        const {patch, error} = cleanUpdate(request.body || {}, e.data);
+        if (error) return reply.code(400).send({error});
+        const next = await rx.applyPatch(e.id, patch, request.user?.name || 'Domma');
+        return {id: next.id, ...next.data, createdAt: next.meta?.createdAt, updatedAt: next.meta?.updatedAt};
+    });
+
+    fastify.delete('/reports/:id', can('manage'), async (request, reply) => {
+        const e = await rx.getReport(request.params.id);
+        if (!e) return reply.code(404).send({error: 'No such report.'});
+        await rx.removeReport(e.id);
+        return {ok: true};
+    });
+
+    fastify.get('/waypoint', can('manage'), async () => {
+        const wp = waypoint();
+        if (!wp) return {available: false, projects: []};
+        try { return {available: true, projects: (await wp.listProjects()) || []}; }
+        catch (err) { return {available: false, projects: [], error: err.message}; }
+    });
+
+    fastify.post('/reports/:id/promote', can('manage'), async (request, reply) => {
+        const wp = waypoint();
+        if (!wp) return reply.code(503).send({error: 'Waypoint Pro is not installed or not enabled on this server.'});
+        const e = await rx.getReport(request.params.id);
+        if (!e) return reply.code(404).send({error: 'No such report.'});
+        if (e.data.issueId) return reply.code(409).send({error: `Already ${e.data.issueKey}.`});
+        const {projectId, type, priority} = request.body || {};
+        if (!projectId) return reply.code(400).send({error: 'Choose a project.'});
+        let issue;
+        try {
+            issue = await wp.createIssue({projectId: String(projectId), title: e.data.title, description: issueDescription({...e.data, site: names()[e.data.site] || e.data.site}),
+                type: String(type || ''), priority: String(priority || ''), reporterName: e.data.userName,
+                source: {plugin: 'feedback', id: e.id, site: e.data.site, url: `#/plugins/feedback/${e.id}`}});
+        } catch (err) {
+            return reply.code(400).send({error: `Waypoint did not make the issue: ${err.message}`});
+        }
+        const status = ['new', 'acknowledged'].includes(e.data.status) ? 'planned' : e.data.status;
+        const next = await rx.applyPatch(e.id, {issueId: String(issue.id), issueKey: String(issue.key || ''), issueStatus: '', status},
+            request.user?.name || 'Domma');
+        return {id: next.id, ...next.data, issueLink: issue.link || ''};
+    });
+}

package/plugins/feedback/plugin.json

@@ -0,0 +1,48 @@
+{
+  "name": "feedback",
+  "displayName": "Feedback",
+  "version": "1.0.0",
+  "tier": "free",
+  "description": "Tell Domma what is broken, missing or good - straight from your admin - and see what became of it: seen, planned, in progress, done, with Domma's reply.",
+  "author": "Domma CMS",
+  "date": "2026-09-27",
+  "icon": "message-square",
+  "permissions": [
+    {
+      "key": "feedback",
+      "label": "Feedback",
+      "group": "Plugins",
+      "icon": "message-square",
+      "description": "Send feedback to Domma and read the replies (send). On the Domma server itself: read, answer and file everything the sites sent (manage).",
+      "actions": [
+        {"key": "send", "label": "Send", "description": "Send feedback to Domma and see what this site has sent"},
+        {"key": "manage", "label": "Manage", "description": "On the Domma server: the inbox of every site's feedback"}
+      ],
+      "grant": ["admin"]
+    }
+  ],
+  "admin": {
+    "css": ["admin/css/index.css"],
+    "sidebar": [
+      {
+        "id": "feedback",
+        "text": "Feedback",
+        "icon": "message-square",
+        "url": "#/plugins/feedback",
+        "section": "#/plugins/feedback",
+        "permission": "feedback",
+        "countUrl": "/api/plugins/feedback/count"
+      }
+    ],
+    "routes": [
+      {"path": "/plugins/feedback", "view": "plugin-feedback", "title": "Feedback - Domma CMS"},
+      {"path": "/plugins/feedback/:id", "view": "plugin-feedback", "title": "Feedback - Domma CMS"}
+    ],
+    "views": {
+      "plugin-feedback": {
+        "entry": "feedback/admin/views/feedback.js?v=1.0.0",
+        "exportName": "feedbackView"
+      }
+    }
+  }
+}

package/plugins/feedback/tests/api.test.js

@@ -0,0 +1,219 @@
+/**
+ * Both sides at once: a SENDER app (a site) whose fetch is wired straight into
+ * a RECEIVER app (the manager) via inject, against the real collection service
+ * in the domma-cms checkout `make test` runs in. The collection is made for the
+ * test and removed after; config/plugins.json is restored byte for byte.
+ */
+import {test, before, after} from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import Fastify from 'fastify';
+import feedback from '../plugin.js';
+
+const PLUGINS = path.resolve('config/plugins.json');
+const COLL = path.resolve('content/collections/feedback-reports');
+const TOKENS = {'tok-acme': 'acme', 'tok-beta': 'beta', 'tok-flood': 'flood'};
+let savedPlugins;
+let manager;
+let dataDir;
+let managerUp = true;
+const notices = [];
+const siteNotices = [];
+
+/** A site's fetch: into the manager app, or a connection failure while it is "restarting". */
+const fetchInto = (app) => async (url, init = {}) => {
+    if (!managerUp) throw new Error('connect ECONNREFUSED 127.0.0.1:8192');
+    const res = await app.inject({method: init.method || 'GET', url: new URL(url).pathname,
+        headers: init.headers, payload: init.body});
+    return {status: res.statusCode, json: async () => res.json()};
+};
+
+async function site({token, user}) {
+    const app = Fastify();
+    await app.register(feedback, {
+        auth: {authenticate: async (req) => { req.user = user; }, requirePermission: () => async () => {}},
+        settings: {}, mode: 'sender', timer: false, dataDir: await fs.mkdtemp(path.join(dataDir, 'site-')),
+        env: {MANAGER_URL: 'http://127.0.0.1:8192/', FLEET_TOKEN: token, SITE_SLUG: TOKENS[token] || 'x'},
+        fetch: fetchInto(manager),
+        hooks: {notify: (n) => siteNotices.push(n), registerNotificationSource() {}}
+    });
+    return app;
+}
+
+const call = async (app, method, url, body, headers) => {
+    const res = await app.inject({method, url, payload: body, headers});
+    let json = null;
+    try { json = res.json(); } catch { /* not JSON */ }
+    return {status: res.statusCode, body: json};
+};
+
+before(async () => {
+    savedPlugins = await fs.readFile(PLUGINS, 'utf8').catch(() => null);
+    await fs.rm(COLL, {recursive: true, force: true});
+    dataDir = await fs.mkdtemp(path.join(os.tmpdir(), 'feedback-test-'));
+    manager = Fastify();
+    await manager.register(feedback, {
+        auth: {authenticate: async (req) => { req.user = {id: 'v1', name: 'Vendor', role: 'super-admin'}; }, requirePermission: () => async () => {}},
+        prefix: '/api/plugins/feedback',
+        settings: {perSiteMax: 6, perSiteMinutes: 10}, mode: 'receiver',
+        slugFromToken: async (h) => TOKENS[String(h || '').replace(/^Bearer\s+/i, '')] || null,
+        siteNames: () => ({acme: 'Acme Ltd', beta: 'Beta Co'}),
+        hooks: {notify: (n) => notices.push(n), registerNotificationSource() {}}
+    });
+});
+
+after(async () => {
+    await manager?.close();
+    delete globalThis.dommaWaypoint;
+    await fs.rm(COLL, {recursive: true, force: true});
+    await fs.rm(dataDir, {recursive: true, force: true});
+    if (savedPlugins === null) await fs.rm(PLUGINS, {force: true});
+    else await fs.writeFile(PLUGINS, savedPlugins);
+});
+
+test('a site sends; the manager attributes it to the token and tells the vendor', async () => {
+    const acme = await site({token: 'tok-acme', user: {id: 'u1', name: 'Sam', email: 'sam@acme.test', role: 'admin'}});
+    let r = await call(acme, 'POST', '/send', {type: 'bug', title: 'Save loses text', description: 'Typed, saved, gone.', severity: 'major',
+        user: {name: 'Mallory'}, site: 'beta'});
+    assert.equal(r.status, 201, JSON.stringify(r.body));
+    assert.equal(r.body.state, 'sent');
+
+    const inbox = (await call(manager, 'GET', '/api/plugins/feedback/reports')).body.reports;
+    assert.equal(inbox.length, 1);
+    assert.equal(inbox[0].site, 'acme', 'the token names the site, not the body');
+    assert.equal(inbox[0].userName, 'Sam', 'the session names the sender, not the body');
+    assert.equal(inbox[0].siteName, 'Acme Ltd');
+    assert.ok(notices.some(n => n.source === 'new-report' && n.title.includes('Acme Ltd')));
+    assert.equal((await call(manager, 'GET', '/api/plugins/feedback/count')).body.count, 1);
+
+    r = await call(acme, 'GET', '/sent');
+    assert.equal(r.body.reachable, true);
+    assert.equal(r.body.reports.length, 1);
+    assert.equal(r.body.reports[0].statusLabel, 'New');
+    await acme.close();
+});
+
+test('an unknown token is refused; each site reads only its own', async () => {
+    let r = await call(manager, 'POST', '/api/plugins/feedback/fleet/submit', {title: 't', description: 'd'}, {authorization: 'Bearer nope'});
+    assert.equal(r.status, 401);
+    r = await call(manager, 'GET', '/api/plugins/feedback/fleet/mine', null, {authorization: 'Bearer nope'});
+    assert.equal(r.status, 401);
+
+    const beta = await site({token: 'tok-beta', user: {id: 'u9', name: 'Bea', email: 'bea@beta.test'}});
+    await call(beta, 'POST', '/send', {type: 'feature', title: 'Dark mode', description: 'Please.'});
+    const mine = (await call(manager, 'GET', '/api/plugins/feedback/fleet/mine', null, {authorization: 'Bearer tok-beta'})).body.reports;
+    assert.deepEqual(mine.map(x => x.title), ['Dark mode'], 'beta never sees acme');
+    for (const k of ['notes', 'userEmail', 'site', 'userId', 'history']) assert.equal(mine[0][k], undefined, `${k} stays on the manager`);
+    await beta.close();
+});
+
+test('a retry of the same report does not make a second one', async () => {
+    const body = {ref: 'same-ref', title: 'Twice', description: 'Sent twice.'};
+    const h = {authorization: 'Bearer tok-beta'};
+    const a = await call(manager, 'POST', '/api/plugins/feedback/fleet/submit', body, h);
+    const b = await call(manager, 'POST', '/api/plugins/feedback/fleet/submit', body, h);
+    assert.equal(a.status, 201);
+    assert.equal(b.status, 200);
+    assert.equal(a.body.id, b.body.id);
+});
+
+test('the per-site throttle and the body limit', async () => {
+    // A site stuck retrying cannot flood: 6 in the window, then 429 - for that site only.
+    const h = {authorization: 'Bearer tok-flood'};
+    for (let i = 0; i < 6; i++) {
+        assert.equal((await call(manager, 'POST', '/api/plugins/feedback/fleet/submit', {title: `n${i}`, description: 'y'}, h)).status, 201);
+    }
+    assert.equal((await call(manager, 'POST', '/api/plugins/feedback/fleet/submit', {title: 'x', description: 'y'}, h)).status, 429);
+    assert.equal((await call(manager, 'POST', '/api/plugins/feedback/fleet/submit', {title: 'x', description: 'y'},
+        {authorization: 'Bearer tok-beta'})).status, 201, 'another site is unaffected');
+    const big = await manager.inject({method: 'POST', url: '/api/plugins/feedback/fleet/submit',
+        headers: {'content-type': 'application/json', authorization: 'Bearer tok-acme'},
+        payload: JSON.stringify({title: 't', description: 'z'.repeat(40 * 1024)})});
+    assert.equal(big.statusCode, 413);
+});
+
+test('the manager restarting: the report waits, then goes', async () => {
+    const acme = await site({token: 'tok-acme', user: {id: 'u2', name: 'Al'}});
+    managerUp = false;
+    let r = await call(acme, 'POST', '/send', {type: 'question', title: 'While down', description: 'Is it?'});
+    assert.equal(r.status, 201);
+    assert.equal(r.body.state, 'waiting');
+    r = await call(acme, 'GET', '/sent');
+    assert.equal(r.body.reachable, false);
+    assert.equal(r.body.reports.find(x => x.title === 'While down').status, 'waiting');
+    managerUp = true;
+    r = await call(acme, 'GET', '/sent');
+    assert.equal(r.body.reachable, true);
+    assert.equal(r.body.reports.find(x => x.title === 'While down').status, 'new', 'sent on the next open');
+    await acme.close();
+});
+
+test('a reply: the site sees it, is told once, and the badge counts it until read', async () => {
+    const acme = await site({token: 'tok-acme', user: {id: 'u1', name: 'Sam'}});
+    await call(acme, 'POST', '/send', {type: 'bug', title: 'Needs a reply', description: 'd'});
+    const report = (await call(manager, 'GET', '/api/plugins/feedback/reports')).body.reports.find(x => x.title === 'Needs a reply');
+    let r = await call(manager, 'PUT', `/api/plugins/feedback/reports/${report.id}`, {status: 'planned', reply: 'On the list.', notes: 'Easy fix'});
+    assert.equal(r.status, 200, JSON.stringify(r.body));
+    siteNotices.length = 0;
+    const sent = (await call(acme, 'GET', '/sent')).body.reports.find(x => x.title === 'Needs a reply');
+    assert.equal(sent.reply, 'On the list.');
+    assert.equal(sent.statusLabel, 'Planned');
+    assert.equal(sent.notes, undefined);
+    assert.equal(sent.unread, true);
+    assert.ok(siteNotices.some(n => n.source === 'reply'));
+    assert.equal((await call(acme, 'GET', '/count')).body.count, 1);
+    await call(acme, 'PUT', `/sent/${sent.id}/seen`, {replyAt: sent.replyAt});
+    assert.equal((await call(acme, 'GET', '/count')).body.count, 0);
+    await acme.close();
+});
+
+test('promote to Waypoint, and follow the issue', async () => {
+    const report = (await call(manager, 'GET', '/api/plugins/feedback/reports')).body.reports.find(x => x.title === 'Save loses text');
+    let r = await call(manager, 'POST', `/api/plugins/feedback/reports/${report.id}/promote`, {projectId: 'p1'});
+    assert.equal(r.status, 503, 'no Waypoint yet');
+    assert.equal((await call(manager, 'GET', '/api/plugins/feedback/waypoint')).body.available, false);
+
+    const made = [];
+    globalThis.dommaWaypoint = {
+        version: 1,
+        listProjects: async () => [{id: 'p1', key: 'CMS', name: 'Domma CMS'}],
+        createIssue: async (input) => { made.push(input); return {id: 'i1', key: 'CMS-12', link: '#/plugins/waypoint-pro/issue/CMS-12'}; },
+        getIssue: async () => ({id: 'i1', key: 'CMS-12', statusName: 'In Review', statusCategory: 'doing'})
+    };
+    assert.deepEqual((await call(manager, 'GET', '/api/plugins/feedback/waypoint')).body.projects.map(p => p.key), ['CMS']);
+    r = await call(manager, 'POST', `/api/plugins/feedback/reports/${report.id}/promote`, {projectId: 'p1', type: 'bug', priority: 'high'});
+    assert.equal(r.status, 200, JSON.stringify(r.body));
+    assert.equal(r.body.issueKey, 'CMS-12');
+    assert.equal(r.body.status, 'planned');
+    assert.equal(made[0].source.plugin, 'feedback');
+    assert.equal(made[0].source.id, report.id);
+    assert.match(made[0].description, /From Sam on Acme Ltd/);
+    assert.equal((await call(manager, 'POST', `/api/plugins/feedback/reports/${report.id}/promote`, {projectId: 'p1'})).status, 409);
+
+    // Waypoint moves the issue: the report follows.
+    await globalThis.dommaFeedback.issueUpdated({sourceId: report.id, issue: {id: 'i1', key: 'CMS-12', statusName: 'Done', statusCategory: 'done'}});
+    r = await call(manager, 'GET', `/api/plugins/feedback/reports/${report.id}`);
+    // Reading it asks Waypoint again, which now says In Review / doing.
+    assert.equal(r.body.status, 'in-progress');
+    assert.equal(r.body.issueStatus, 'In Review');
+
+    // Declined by hand stays declined.
+    await call(manager, 'PUT', `/api/plugins/feedback/reports/${report.id}`, {status: 'declined'});
+    await globalThis.dommaFeedback.issueUpdated({sourceId: report.id, issue: {statusName: 'Done', statusCategory: 'done'}});
+    delete globalThis.dommaWaypoint;
+    r = await call(manager, 'GET', `/api/plugins/feedback/reports/${report.id}`);
+    assert.equal(r.body.status, 'declined');
+});
+
+test('a site the manager did not start cannot send, and says so', async () => {
+    const app = Fastify();
+    await app.register(feedback, {
+        auth: {authenticate: async (req) => { req.user = {id: 'u', name: 'U'}; }, requirePermission: () => async () => {}},
+        settings: {}, mode: 'sender', timer: false, env: {}, dataDir: await fs.mkdtemp(path.join(dataDir, 'lone-')), hooks: {}
+    });
+    assert.equal((await call(app, 'GET', '/mode')).body.connected, false);
+    assert.equal((await call(app, 'POST', '/send', {title: 't', description: 'd'})).status, 409);
+    await app.close();
+});

package/plugins/feedback/tests/shape.test.js

@@ -0,0 +1,87 @@
+import {test} from 'node:test';
+import assert from 'node:assert/strict';
+import {
+    buildPayload, cleanSubmission, cleanUpdate, createThrottle, issueDescription, receivedReport, senderView, statusFromIssue
+} from '../lib/shape.js';
+import {mergeReports} from '../lib/sender.js';
+
+test('a submission is cleaned, and says nothing about who sent it', () => {
+    assert.equal(cleanSubmission({title: '  ', description: 'x'}).error, 'Give it a short title.');
+    assert.equal(cleanSubmission({title: 'x', description: ''}).error, 'Say a little more in the description.');
+    const {report} = cleanSubmission({type: 'nonsense', title: 'A'.repeat(500), description: 'd', severity: 'blocker', user: {name: 'Mallory'}});
+    assert.equal(report.type, 'other');
+    assert.equal(report.title.length, 140);
+    assert.equal(report.severity, '', 'severity is for bugs only');
+    assert.equal(report.user, undefined);
+    assert.equal(cleanSubmission({type: 'bug', title: 't', description: 'd', severity: 'blocker'}).report.severity, 'blocker');
+});
+
+test('the payload takes the user from the session', () => {
+    const p = buildPayload({report: {type: 'bug', title: 't', description: 'd'}, user: {id: 'u1', name: 'Sam', email: 's@x.io', role: 'admin'},
+        cmsVersion: '0.91.0', site: 'acme', ref: 'r1'});
+    assert.deepEqual(p.user, {id: 'u1', name: 'Sam', email: 's@x.io'});
+    assert.equal(p.ref, 'r1');
+    assert.equal(p.cmsVersion, '0.91.0');
+});
+
+test('the manager attributes a report to the token, never the body', () => {
+    const {data} = receivedReport({title: 't', description: 'd', site: 'someone-else', status: 'done', notes: 'sneaky', user: {name: 'Sam'}}, 'acme');
+    assert.equal(data.site, 'acme');
+    assert.equal(data.status, 'new');
+    assert.equal(data.notes, '');
+    assert.equal(data.userName, 'Sam');
+});
+
+test('a site sees a whitelist of its report', () => {
+    const v = senderView({id: 'e1', data: {title: 't', status: 'planned', notes: 'internal', userEmail: 'x@y', site: 'acme', reply: 'Thanks'},
+        meta: {createdAt: '2026-09-27T10:00:00Z'}});
+    assert.equal(v.notes, undefined);
+    assert.equal(v.userEmail, undefined);
+    assert.equal(v.site, undefined);
+    assert.equal(v.statusLabel, 'Planned');
+    assert.equal(v.reply, 'Thanks');
+});
+
+test('a Waypoint issue moves the report, but not a declined one', () => {
+    assert.equal(statusFromIssue('todo', 'new'), 'planned');
+    assert.equal(statusFromIssue('doing', 'planned'), 'in-progress');
+    assert.equal(statusFromIssue('done', 'in-progress'), 'done');
+    assert.equal(statusFromIssue('done', 'declined'), 'declined');
+    assert.equal(statusFromIssue('weird', 'planned'), 'planned');
+});
+
+test('updates: known statuses only, an unchanged reply is not a new reply', () => {
+    assert.equal(cleanUpdate({status: 'lost'}).error, 'That is not a status.');
+    assert.equal(cleanUpdate({}).error, 'Nothing to change.');
+    assert.deepEqual(cleanUpdate({status: 'done', reply: 'Same'}, {reply: 'Same'}).patch, {status: 'done'});
+});
+
+test('the throttle allows max in the window, then waits', () => {
+    const ok = createThrottle({max: 2, windowMs: 1000});
+    assert.equal(ok('a', 0), true);
+    assert.equal(ok('a', 10), true);
+    assert.equal(ok('a', 20), false);
+    assert.equal(ok('b', 20), true, 'per site');
+    assert.equal(ok('a', 1015), true, 'the window moves on');
+});
+
+test('the issue text carries where it came from', () => {
+    const t = issueDescription({description: 'It broke', userName: 'Sam', site: 'Acme', cmsVersion: '0.91.0', severity: 'major'});
+    assert.match(t, /It broke/);
+    assert.match(t, /From Sam on Acme/);
+    assert.match(t, /Domma CMS 0\.91\.0/);
+});
+
+test('the list merges the manager view with what is still waiting', () => {
+    const outbox = [
+        {ref: 'a', state: 'sent', payload: {title: 'A'}, createdAt: '2026-09-27T09:00:00Z'},
+        {ref: 'b', state: 'waiting', payload: {title: 'B', user: {name: 'Sam'}}, createdAt: '2026-09-27T11:00:00Z', lastError: 'down'}
+    ];
+    const remote = [{id: 'e1', ref: 'a', title: 'A', reply: 'Yes', replyAt: '2026-09-27T12:00:00Z', createdAt: '2026-09-27T09:00:00Z'}];
+    const list = mergeReports(outbox, remote, {});
+    assert.deepEqual(list.map(r => r.title), ['B', 'A']);
+    assert.equal(list[0].statusLabel, 'Waiting to send');
+    assert.equal(list[1].unread, true);
+    assert.equal(mergeReports(outbox, remote, {e1: '2026-09-27T12:00:00Z'})[1].unread, false, 'read once seen');
+    assert.equal(mergeReports(outbox, null, {}).length, 2, 'manager unreachable: the outbox copy stands in');
+});