domma-cms 1.6.59 → 1.7.0

package/docs/superpowers/plans/2026-06-26-surveys-HANDOFF.md

@@ -0,0 +1,68 @@
+# Surveys Pro Plugin - Wake-up Handoff (2026-06-26)
+
+Branch: **`feat/surveys-plugin`** (off `main`). Working tree clean except your pre-existing
+`content/collections/projects/data.json` change (untouched by me).
+
+## Status: 19 of 20 tasks done. Server side fully built + tested. UI built but NOT browser-verified.
+
+### Done & node-verified (32 tests passing, one commit per task)
+- 4 collection schemas (`surveys-contacts/groups/surveys/invites`)
+- Libs: `tokens`, `ledger`, `submit` (intrinsic anonymity - full two-stage reviewed), `audience`, `campaigns`, `sending`, `stats` (with the `renderDistribution` charts seam)
+- Admin API `plugin.js`: campaign + audience CRUD, import-from-contacts, send/reminder, stats, export, `[survey]` shortcode registration, `surveys` permission family
+- Public `plugin.public.js`: tokenised submit endpoint, hosted page `GET /survey/:slug`, scheduler `/due-work` + `/run` contract (DRY `runSend`)
+
+Run the suite:
+```
+node --test tests/surveys/tokens.test.js tests/surveys/ledger.test.js tests/surveys/submit.test.js \
+  tests/surveys/audience.test.js tests/surveys/campaigns.test.js tests/surveys/sending.test.js \
+  tests/surveys/stats.test.js tests/surveys/plugin-admin.test.js tests/surveys/plugin-send.test.js \
+  tests/surveys/public-submit.test.js tests/surveys/due-work.test.js
+```
+
+### Built but UNVERIFIED (no browser run - honesty rule: I did not click anything)
+- Hosted page `templates/survey-page.html` + client `public/survey.mjs` + `public/survey.css`
+- Admin views: `surveys.js`, `survey-editor.js`, `audience.js`, `results.js` (+ templates) + `public/dist-shared.mjs`
+
+## The ONE remaining task (10.2) - do this together when you're back
+
+### Step 1 - Enable + restart (YOURS; I must not touch the always-on :4096 server)
+1. Confirm the server will run from this branch (`git branch --show-current` → `feat/surveys-plugin`).
+2. Enable the plugin: add/confirm `surveys` enabled in `config/plugins.json` (check an existing entry's shape first - I deliberately did NOT edit this file).
+3. Optionally set a `schedulerToken` under the surveys plugin settings in `config/plugins.json` (a `dcms_...` value) so `/due-work` + `/run` are reachable by domma-cms-manager; leave empty to keep them 403/disabled.
+4. Restart the server so `setupPlugin` seeds the four real collections (the stub-schema test artefacts were removed, so the real field schemas will seed cleanly).
+5. Grant the `surveys` permission to your admin role in the role editor (it is NOT back-filled - same gotcha as Menus/Projects).
+
+### Step 2 - Browser verification pass (MINE, once the server is up at 192.168.1.4:4096)
+I'll load each surface and fix issues. **Known likely fixes (flagged by the implementers, unverified):**
+
+**Hosted page / client / shortcode (`survey.mjs`, `[survey]`):**
+**A source-grounded correction pass (commits after the first UI build) already resolved the items struck through below - confirmed against the real Domma source, but still browser-UNVERIFIED.**
+
+**Resolved by source-grounded corrections (verify in browser, but should be right):**
+- ~~Embed mount bug~~ - `survey.mjs` now scans BOTH `#survey-mount` (hosted) and `.survey-mount` (embed).
+- ~~`F.create` signature~~ - `survey-editor.js`/`audience.js` now use the canonical `F.create(blueprintObject, defaults, {showSubmitButton:false}).renderTo()` with `[name=]` value collection + own Save button (transcribed from `admin/js/views/collection-entries.js`; field types `string`/`textarea`/`multiselect`/`select` verified against Domma's `_buildInput`).
+- ~~Inline `onclick`~~ - list view now uses `data-slug` + unnamespaced `$container.off('click',…).on('click',…)` delegation (proven api-tokens.js pattern; DOMPurify strips inline onclick).
+- ~~Icons missing~~ - `send`/`bell`/`clipboard-list`/`bar-chart`/`edit`/`arrow-left` all CONFIRMED to exist as Domma icon keys.
+- ~~`E.modal` shape~~ - `{element, open(), close()}` confirmed correct (collection-entries.js:389).
+- ~~`T.create` columns~~ - `{key, title, render→HTML string}` confirmed correct; native el via `.get(0)`.
+- ~~`templateUrl` leading slash~~ - `/plugins/surveys/admin/templates/…` matches the working contacts plugin.
+
+**Still genuinely needing a browser (could not confirm from source):**
+1. Hosted client: `Domma.forms.render(wrapper, blueprint, initialData, {onSubmit})` - is `onSubmit` the real submission hook (vs. the form firing its own POST)? Highest-risk hosted-page item.
+2. `multiselect` for `groupIds` pre-highlighting selected options on EDIT; `date` value round-trip for `opensAt`/`closesAt`.
+3. `<script type="module">` in the `[survey]` shortcode output may be stripped by the page sanitiser → embed may need an injection snippet / `site.js` hook to load `survey.mjs`. (Hosted page loads it directly - fine.)
+4. `.mjs` MIME from the `/plugins/` static mount executes as a module; dist asset paths in `survey-page.html`.
+5. Shared import `import {renderDistribution} from '/plugins/surveys/public/dist-shared.mjs'` resolves in the admin module loader.
+6. Authed blob download for CSV/JSON export.
+
+### Step 3 - End-to-end smoke (together)
+- Create a Form → create a Survey (identified) → add contacts to a group → Send → open the hosted link `/survey/<slug>?t=<code>` → complete → confirm Results show 100% + the answer; reload → "already completed".
+- Repeat with an **anonymous** survey; confirm the CSV/JSON export contains **no** contact identity.
+
+## Carried-forward concerns (documented, not bugs to fix now)
+- One-response-per-invite is **not atomic** on the file adapter (check-then-act race on concurrent same-token submits). Documented in `plugins/surveys/CLAUDE.md`; mitigation noted on plan Task 8.1.
+- Anonymity is **row-level, not timing-proof** (ledger `completedAt` ↔ response `createdAt` correlation at low volume). Documented in CLAUDE.md.
+
+## Upstream stubs (separate repos, not this branch)
+- `docs/superpowers/specs/2026-06-26-domma-charts-upstream-proposal.md` (`domma-js`)
+- `docs/superpowers/specs/2026-06-26-manager-scheduler-upstream-proposal.md` (`domma-cms-manager`)