@mhosaic/feedback-cli 0.13.0 → 0.14.0

package/skills/integrate-feedback/references/verify-install.md

@@ -0,0 +1,151 @@
+# Verify install — live smoke test
+
+After the consumer has installed the widget, run this end-to-end smoke test to confirm everything actually works. Don't claim "done" until this is green.
+
+---
+
+## Step 1 — Run the CLI verify
+
+```bash
+npx @mhosaic/feedback-cli@latest verify \
+  --origin <consumer-dev-origin> \
+  --with-test-report
+```
+
+`<consumer-dev-origin>` is the URL where the consumer's app runs locally — `http://localhost:5173` for Vite, `http://localhost:3000` for Next/Remix, etc.
+
+Expected output (all green):
+
+```
+✓ .env.local exists with both keys
+✓ API key starts with pk_proj_
+✓ Endpoint is a valid http(s) URL
+✓ Endpoint reachable over network
+✓ CORS allows POST from <origin>
+✓ POST /api/feedback/v1/reports/ accepts the public key  (submitted (report id: …) — delete it from /reports if you don't want noise)
+
+All checks passed.
+```
+
+If any check is red, **STOP**. Don't proceed to step 2 until they're all green. The hint column tells you what to fix; the diagnostic table at the bottom of this doc covers every failure mode.
+
+---
+
+## Step 2 — Start the consumer's dev server
+
+In the consumer's repo:
+
+```bash
+pnpm dev  # or npm run dev / yarn dev / bun dev
+```
+
+Wait for the server to print its URL (e.g. `Local: http://localhost:5173`).
+
+---
+
+## Step 3 — Drive Chrome to the dev URL
+
+```
+mcp__claude-in-chrome__tabs_create_mcp  # or reuse an existing tab
+mcp__claude-in-chrome__navigate(tabId, url=<dev-url>)
+mcp__claude-in-chrome__computer(action="screenshot")
+```
+
+Inspect the screenshot. You should see:
+
+1. The consumer's actual UI rendered (their app loaded successfully)
+2. A small floating action button (FAB) in the bottom-right corner — a circle with a chat-bubble or megaphone icon
+
+If the FAB is missing, see the diagnostic table at the bottom.
+
+---
+
+## Step 4 — Open DevTools console; verify no widget errors
+
+```
+mcp__claude-in-chrome__read_console_messages(pattern="mhosaic|feedback|widget")
+```
+
+Acceptable: a "widget mounted" or "init complete" debug line. Not acceptable: any `error` or `unhandledrejection` mentioning `@mhosaic/feedback`, `pk_proj_`, CORS, or fingerprint.
+
+If errors appear, surface them to the user before clicking the FAB — they may already explain a failure that the visual test wouldn't catch.
+
+---
+
+## Step 5 — Click the FAB and submit a test report
+
+Use `mcp__claude-in-chrome__find(query="feedback FAB or feedback button")` to locate the element. Click it.
+
+A modal/sheet should open inviting the user to write a description. Fill in:
+
+> `[INTEGRATE-FEEDBACK SMOKE TEST] integration verified at <ISO timestamp>`
+
+…and submit. The widget should close itself + show a success toast.
+
+If the form rejects the submit with a 4xx error, capture the network response via:
+
+```
+mcp__claude-in-chrome__read_network_requests(urlPattern="/api/feedback/v1/reports/")
+```
+
+and surface the status code + response body.
+
+---
+
+## Step 6 — Confirm the report landed in admin
+
+Drive Chrome to `https://software-factory-3tbbu.ondigitalocean.app/reports`. You may need to log in if the operator's session expired.
+
+Filter by description containing `[INTEGRATE-FEEDBACK SMOKE TEST]`. The new report should appear at the top of the list.
+
+Click into it. Verify:
+- Project = the project the operator just provisioned
+- Submitter = whatever identity was wired (anonymous-id, real user, etc.)
+- Page URL = the consumer's dev URL
+- Status = new
+
+Screenshot this to give the user proof-of-life.
+
+---
+
+## Step 7 — (Optional cleanup) delete the smoke-test reports
+
+After confirming, the operator (not the consumer) can clean up the noise:
+
+1. Admin SPA `/reports`, filter by description containing `[INTEGRATE-FEEDBACK SMOKE TEST]` and `[mhosaic-feedback verify]`
+2. Bulk select and delete
+
+Skip this step if the consumer wants to keep the smoke-test reports as a paper trail.
+
+---
+
+## Diagnostic table — when checks fail
+
+| Symptom | Likely cause | Fix |
+|---|---|---|
+| `✗ .env.local exists with both keys` | CLI init never ran, or ran in a different directory | Re-run `mhosaic-feedback init` from the project root |
+| `✗ API key starts with pk_proj_` | Operator pasted the wrong key (e.g. `sk_proj_…`, an MCP key) | Operator mints a *public* widget key (`kind: "public"`) in admin SPA |
+| `✗ Endpoint reachable over network` (network error) | DNS, firewall, offline, or wrong endpoint URL | Verify the URL in `.env.local`; try `curl -I <endpoint>/admin/login/` |
+| `✗ Endpoint reachable` (5xx) | Backend is down or mid-deploy | Wait 1–2 minutes; check DO App Platform deploy status |
+| `✗ CORS allows POST from <origin>` | Operator forgot to add this origin to `allowed_origins` | Operator opens admin SPA → Edit project → adds the dev URL (e.g. `http://localhost:5173`) |
+| `✗ POST /api/feedback/v1/reports/` returns 401 | Key invalid or revoked | Operator mints a new key |
+| `✗ POST /api/feedback/v1/reports/` returns 403 with "origin not allowed" | Same as CORS row above | Operator adds the origin |
+| FAB doesn't render in dev | `identify()` not called with a non-empty `id` | Wire identify per `identify-snippets.md`, OR for testing pass `{id: 'test-user'}` |
+| FAB renders but form submit fails with 403 | Origin not in `allowed_origins` (Vite dev URL differs from prod URL) | Operator adds the dev URL |
+| FAB renders but form submit fails with 400 | Serializer rejected the payload (description empty, env unknown, etc.) | Read DevTools network response — usually a clear field-level error |
+| Console error: `Failed to load module` for `@mhosaic/feedback` | Vite cache mismatch | Stop dev server, delete `node_modules/.vite`, restart |
+| Console error: `Unhandled CORS preflight failure` | Origin not allowlisted on the backend side | Operator adds the origin; consumer hard-reloads |
+| Widget submits anonymous reports despite identify() running | identify() called in a stale closure (effect dep array missing the user) | Re-read identify-snippets.md — every snippet has the right deps |
+| `verify --with-test-report` succeeds but the report doesn't appear in admin | Browser cache; report is filtered by default (e.g. `synthetic=true` hides it) | Refresh admin /reports; toggle "show synthetic" filter |
+
+---
+
+## When to escalate
+
+If after 3 fix-iterations the smoke test still fails, escalate to the operator with:
+
+1. The CLI verify output (full text)
+2. A DevTools network request showing the actual server response
+3. A screenshot of the dev UI showing FAB state
+
+The operator can correlate the failure against the project's `allowed_origins`, key status, and `share_reports_with_widget` flag in the admin SPA — that catches >90% of "weird" failures the consumer can't debug on their own.