@explorer02/cfm-survey-sdk 0.2.3 → 0.2.5

package/templates/docs/00-integration/wizard-api.md

@@ -0,0 +1,126 @@
+# Wizard API — EC2 fallback (`customize-ui` only)
+
+> **Default wizard is `npx cfm-sdk customize` on localhost** — no EC2 API needed.  
+> This doc applies **only** when the client customizes from another device.
+
+Base URL: `CFM_DEPLOY_API_BASE` — default: `http://43.204.26.213:3000`
+
+## Architecture
+
+```mermaid
+flowchart LR
+  CLI[customize-ui CLI] -->|PUT preview files| Disk[EC2 disk data/wizard-sessions/]
+  Client[Client browser] --> SPA[wizard-app SPA]
+  SPA -->|GET /api/inventory| API[deploy-api]
+  SPA -->|iframe /previews/...| Disk
+  SPA -->|POST /api/save-config| API
+  API -->|final config + logo| S3[S3 hosting bucket]
+  CLI -->|poll GET /wizard/config| API
+```
+
+| During session | Storage |
+|----------------|---------|
+| Preview HTML | EC2 disk (`WIZARD_DATA_DIR/{sessionId}/previews/`) |
+| Seed config | EC2 disk (`seed-config.json`) |
+| Temp logo | EC2 disk (`assets/`) |
+| **On submit** | Final JSON + permanent logo → S3 |
+
+Previews are **not** loaded from S3 during customization — avoids "Storage service unavailable" on preview iframes.
+
+## Client wizard link
+
+```
+{CFM_DEPLOY_API_BASE}/wizard-app/index.html?session={sessionId}&secret={sessionSecret}
+```
+
+| Route | Role |
+|-------|------|
+| `/wizard-app/` | Wizard SPA |
+| `/api/inventory` | Session metadata + `previewManifest` (local-server API) |
+| `/previews/{sessionId}/{key}/index.html` | Component preview iframes |
+| `/api/save-config` | Client submit (same as local `customize`) |
+
+## Local-server routes (`/api/*`, `/previews/*`)
+
+Same contract as `packages/sdk/src/cli/customize.ts`:
+
+### `GET /api/inventory?session=&secret=`
+
+Returns `{ surveyTypes, instanceId, previewUrl, previewManifest, initialConfig, localServer: true }`.
+
+### `GET /api/preview-url`
+
+Health check for preview availability indicator.
+
+### `POST /api/upload-logo?session=&secret=`
+
+Body: `{ filename, base64 }` — stores logo on EC2 disk for session.
+
+### `POST /api/save-config?session=&secret=`
+
+Body: full `survey-ui-config.json`. Persists final config + logo to S3, cleans session disk.
+
+## Session management (`/wizard/*`)
+
+### `POST /wizard/session/start`
+
+**Auth:** `Authorization: Bearer {JWT}`
+
+**Body:** `{ files, surveyTypes, initialConfig }`
+
+**Response:** `{ sessionId, sessionSecret, wizardUrl, uploads[], localServer: true }`
+
+`uploads[].uploadUrl` → `PUT /wizard/session/:sessionId/preview-file?path=previews/...` (EC2 disk, not S3 presign).
+
+### `PUT /wizard/session/:sessionId/preview-file?path=...`
+
+**Auth:** `X-Wizard-Session` + `X-Wizard-Session-Id`
+
+Raw file body → written to session disk.
+
+### `POST /wizard/previews/upload/complete`
+
+**Auth:** JWT. Verifies all files on disk; activates session; builds manifest with `/previews/{sessionId}/…` URLs.
+
+### `POST /wizard/session/quit`
+
+Deletes session disk folder + in-memory session. CLI poll returns `status: abandoned`.
+
+### `GET /wizard/config/:surveyId?sessionId=`
+
+CLI poll after client submit.
+
+- **pending** — waiting
+- **abandoned** — client quit
+- **ready** — `{ config, logoUrl, … }`
+
+## Env (deploy-api)
+
+```bash
+WIZARD_DATA_DIR=./data/wizard-sessions   # preview + seed + temp logo on disk
+WIZARD_SESSION_TTL_MS=7200000
+HOSTING_BUCKET=...                        # final config + permanent logo only
+CLOUDFRONT_BASE_URL=...
+```
+
+## IAM (EC2 instance role)
+
+Required for **submit** (not previews):
+
+- `s3:PutObject`, `s3:GetObject` on hosting bucket
+- `cloudfront:CreateInvalidation` (logo cache bust)
+
+## CLI flow
+
+```bash
+export CFM_INSTANCE_ID="..." CFM_DEPLOY_API_BASE="http://43.204.26.213:3000"
+npx cfm-sdk customize-ui
+```
+
+1. `export-previews` on agent machine
+2. Upload preview files to EC2 disk
+3. Print client wizard link
+4. Poll until `status: ready`
+5. Write `.final.json` + `.diff.md`
+
+See [`wizard-config-handoff.md`](wizard-config-handoff.md), [`ui-customization-wizard.md`](ui-customization-wizard.md).

package/templates/docs/00-integration/wizard-config-handoff.md

@@ -0,0 +1,292 @@
+# Wizard Config Handoff — Wait, Capture, Apply
+
+> **Phase 6b → 6c.** Read with [`ui-customization-wizard.md`](ui-customization-wizard.md) and [`apply-ui-config.md`](apply-ui-config.md).  
+> Pipeline: [`agent-execution-flow.md`](agent-execution-flow.md).
+
+This doc tells the agent **exactly** how to wait for the client to finish the wizard, capture the JSON output, and apply **every** change without omission.
+
+---
+
+## Prime rule
+
+**Do not apply wizard changes until the client has submitted the wizard.**
+
+- **Default (`customize`):** CLI blocks until client saves — wait for `✅ UI configuration saved`.
+- **Remote client (`customize-ui`):** CLI blocks and polls until status `ready`.
+
+**Do not** guess final colors from memory or proceed to deploy before the wizard CLI exits 0.
+
+---
+
+## Default flow — `npx cfm-sdk customize`
+
+### Step 1 — Agent runs CLI (and waits)
+
+```bash
+npx cfm-sdk customize
+```
+
+The CLI will:
+
+1. Export all 11 component preview pages (`export-previews` if needed)
+2. Start wizard at `http://localhost:4200`
+3. Open browser on the **agent machine**
+4. **Block** until client clicks **Review & Build**
+5. Write `survey-ui-config.json` and exit 0
+
+**Agent must:**
+
+- [ ] Client is on the **same machine** (can see `localhost:4200`)
+- [ ] Keep terminal open until `✅ UI configuration saved`
+- [ ] Apply per Phase 6c from `survey-ui-config.json`
+
+**Artifact:** `survey-ui-config.json` — apply source for local flow.
+
+**Logo on local wizard (critical for AWS deploy):**
+
+When the client uploads a logo in the local wizard:
+
+1. CLI writes the file to `public/logo_{timestamp}_{name}.jpg` via `POST /api/upload-logo`.
+2. Saved config has `global.logo.fileName` — preview `data:` URL is **not** persisted (stripped on save).
+3. Agent **must** set `Header.tsx` `data-cfm-logo` to `src="./{fileName}"` during Phase 6c.
+4. `yarn build` copies `public/` → `out/`; Phase 7 uploads `out/` to `sites/{surveyId}/{deployId}/`.
+
+The logo is **not** fetched from wizard memory on CloudFront — only from the deploy bundle. See [`aws-deploy.md`](aws-deploy.md) § Logos & local assets.
+
+---
+
+## Remote client flow — `customize-ui` (fallback only)
+
+### Step 1 — Agent runs CLI (and waits)
+
+```bash
+export CFM_INSTANCE_ID="<JWT>"
+export CFM_DEPLOY_API_BASE="<EC2 URL>"
+npx cfm-sdk customize-ui
+```
+
+**Default is review mode** (no flags). The CLI will:
+
+1. Export component preview pages (`export-previews`)
+2. Upload preview HTML to **EC2 disk** (local-server model — same as agent `customize`)
+3. Print the **deployed EC2 wizard link** — agent **must share this URL with the client**
+4. **Poll every ~3s** (`GET /wizard/config/:surveyId`) until the client submits
+5. Print `✅ Configuration ready` when `status === 'ready'`
+
+### Deployed wizard link (give to client after preview upload)
+
+The client does **not** use localhost. After previews are uploaded, the CLI prints:
+
+```
+🔗 Client wizard link — share with the client:
+   http://43.204.26.213:3000/wizard-app/index.html?session=<uuid>&secret=<hex>
+```
+
+- **Previews:** stored on **EC2 disk** (`WIZARD_DATA_DIR/{sessionId}/previews/`); wizard iframes load via `GET /previews/{sessionId}/{component}/index.html` (local-server API — same model as `customize`)
+- **Wizard UI:** served from EC2 at `/wizard-app/`; inventory via `GET /api/inventory`
+- **On submit:** final config + permanent logo → S3 only
+
+Set `CFM_DEPLOY_API_BASE=http://43.204.26.213:3000` (or your EC2 host). The link is built from that base + session credentials returned by `POST /wizard/session/start`.
+
+**Agent must:**
+
+- [ ] Keep the terminal process **running** — do not Ctrl+C while polling
+- [ ] Tell the client: *"Please complete all wizard steps and click **Review & Build** / save to finish."*
+- [ ] Wait until CLI exits **0** with `Configuration ready`
+- [ ] **Not** start Phase 6c apply until this completes
+
+**Timeout:** default 2 hours (`CFM_WIZARD_TIMEOUT_MS`). If timeout, ask client to re-run or use `fetch-ui-config` (see §5).
+
+### Step 2 — Review artifacts (written on success)
+
+| File | Role |
+|------|------|
+| `survey-ui-config.seed.json` | Snapshot before client edits |
+| `survey-ui-config.final.json` | Client config + `global.logo.url` (public CloudFront URL) |
+| `survey-ui-config.diff.json` / `.diff.md` | Every changed path — **read before apply** |
+| `survey-ui-config.json` | Still **seed** until `confirm-ui-config` |
+| `public/{logoFileName}` | Logo file downloaded from `logoUrl` |
+
+Poll response includes `logoUrl` and `logoKey` — CLI merges `logo.url` into final JSON.
+
+**EC2 logo vs deploy bundle:** `logoUrl` points to `sites/{surveyId}/assets/{fileName}` on CloudFront. That path is for **wizard handoff** (download into `public/` via `confirm-ui-config`). The **live survey** loads the logo from `sites/{surveyId}/{deployId}/{fileName}` only after you rebuild and run Phase 7 deploy. Apply `data-cfm-logo src="./{fileName}"` then deploy — see [`aws-deploy.md`](aws-deploy.md) § Logos & local assets.
+
+**If all diff counts are 0:** client submitted without changes — still verify; skip heavy apply.
+
+### S3 garbage collection
+
+| When | Deleted | Kept |
+|------|---------|------|
+| Client **Review & Build** | EC2 session disk folder (`data/wizard-sessions/{sessionId}/`) | `sites/{surveyId}/assets/{logo}`, `wizard/config.json` |
+| Client **Quit** (or tab close) | Same session prefix — `POST /wizard/session/quit` | N/A |
+| Session **expires** (2h default) | Same session prefix — auto sweep every 5 min | N/A |
+
+### Step 3 — Agent reads diff before touching code
+
+```bash
+# Agent MUST open and read:
+cat survey-ui-config.diff.md
+```
+
+For **every** section in the diff (`Changed`, `Added`, `Removed`):
+
+1. Find the config path (e.g. `global.colorScheme.primary`)
+2. Look up apply target in [`apply-ui-config.md`](apply-ui-config.md) § Complete mapping
+3. Apply to the listed file/CSS var/`data-cfm-*` attribute
+4. Mark the path done (mental checklist or notes in `implementation_plan.md`)
+
+**Blocking rule:** If a path appears in the diff, it **must** be reflected in the codebase after Phase 6c.
+
+### Step 4 — Apply to codebase (Phase 6c)
+
+Follow [`apply-ui-config.md`](apply-ui-config.md) using **`survey-ui-config.final.json`** as input.
+
+Order:
+
+1. Validate `survey-ui-config.final.json` against `templates/survey-ui-config.schema.json`
+2. Regenerate `src/styles/survey-theme.css` from **all** tokens in final config (not only diff paths — full sync prevents missed derived vars)
+3. Apply `data-cfm-*` content patches (title, buttons, footer links, logo)
+4. Apply layout toggles in `SurveyPage` / chrome
+5. Apply `placeholders`, `customFields`, `debug` in hook options
+6. Re-run `bash templates/verify-agent-build.sh` and `npm run build`
+
+### Step 5 — Promote config + logo
+
+After codebase apply succeeds:
+
+```bash
+export CFM_INSTANCE_ID="<JWT>"
+export CFM_DEPLOY_API_BASE="<EC2 URL>"
+npx cfm-sdk confirm-ui-config
+```
+
+This:
+
+- Copies `survey-ui-config.final.json` → `survey-ui-config.json`
+- Downloads logo to `public/{fileName}` when `global.logo.fileName` is set
+
+**Do not run `confirm-ui-config` before applying tokens to the codebase** — you would promote JSON while the UI still shows seed styling.
+
+Optional: `npx cfm-sdk confirm-ui-config --diff-only` to re-print diff without writing.
+
+---
+
+## Local flow (`customize`)
+
+```bash
+npx cfm-sdk customize
+```
+
+1. CLI starts wizard at `http://localhost:4200`
+2. **Blocks** until client clicks save → `POST /api/save-config`
+3. Writes **`survey-ui-config.json` directly** (no `.final.json` / diff artifacts)
+4. Prints `✅ UI configuration saved` and exits
+
+**Agent must:**
+
+- [ ] Wait for CLI to exit 0 after client saves
+- [ ] Apply from `survey-ui-config.json` per [`apply-ui-config.md`](apply-ui-config.md)
+- [ ] No `confirm-ui-config` step (not used locally)
+
+---
+
+## Legacy AWS mode (`--apply`)
+
+```bash
+npx cfm-sdk customize-ui --apply
+```
+
+Writes final config + logo immediately (no review artifacts). Still requires Phase 6c codebase apply from `survey-ui-config.json`.
+
+**Prefer default review mode** so the agent can audit `survey-ui-config.diff.md` before apply.
+
+---
+
+## Detached session (`--no-wait`)
+
+```bash
+npx cfm-sdk customize-ui --no-wait
+# CLI prints wizard URL and exits — client works asynchronously
+```
+
+When client finishes:
+
+```bash
+export CFM_WIZARD_SESSION_ID="<sessionId from CLI output>"
+npx cfm-sdk fetch-ui-config
+# Writes .final.json + .diff.md — then apply + confirm-ui-config
+```
+
+**Do not apply** until `fetch-ui-config` succeeds.
+
+---
+
+## Agent ↔ client script
+
+**When starting wizard (tell client after you send the link):**
+
+> *"I've uploaded your survey component previews to the cloud. Open this customization link: [paste deployed wizard URL]. Adjust branding, colors, and question-type styling — the preview panel shows your real components. When finished, click **Review & Build** on the last step. I'll wait here until your changes are saved."*
+
+**While waiting (agent):**
+
+- Do not refactor unrelated code
+- Do not start deploy
+- Do not re-run `customize-ui` (overwrites session artifacts)
+
+**After CLI success (tell client):**
+
+> *"Your wizard changes are captured. I'm applying them to the survey UI now and will verify the build."*
+
+---
+
+## Phase checklist
+
+### Phase 6b — Wizard session
+
+- [ ] Client explicitly said yes to wizard (INPUT 3)
+- [ ] `CFM_INSTANCE_ID` and `CFM_DEPLOY_API_BASE` set
+- [ ] Ran `npx cfm-sdk customize-ui` (or `customize` locally)
+- [ ] **Waited** until CLI exit 0 (`Configuration ready` or `UI configuration saved`)
+- [ ] AWS: `survey-ui-config.final.json` and `survey-ui-config.diff.md` exist
+- [ ] Read `survey-ui-config.diff.md` completely
+
+### Phase 6c — Apply (no skipped paths)
+
+- [ ] Applied from **`survey-ui-config.final.json`** (AWS) or **`survey-ui-config.json`** (local)
+- [ ] Every diff path in `changed` + `added` + `removed` addressed
+- [ ] `src/styles/survey-theme.css` fully synced to final config
+- [ ] All `data-cfm-*` content hooks updated
+- [ ] Logo file exists in `public/` when config has `global.logo.fileName`
+- [ ] `out/{fileName}` exists after build when logo configured (AWS deploy gate)
+- [ ] `Header.tsx` uses `data-cfm-logo src="./{fileName}"` — not `data:` or `/assets/` URL
+- [ ] `placeholders` / `customFields` / `debug` wired if present in final
+- [ ] AWS: ran `npx cfm-sdk confirm-ui-config` after codebase apply
+- [ ] `verify-agent-build.sh` + `npm run build` pass
+- [ ] Visually spot-check: header, footer, progress, one question type from inventory
+
+---
+
+## Common mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Killed CLI during poll | Re-run `customize-ui`; client re-submits |
+| Client quit wizard | CLI exits with abandon message; S3 GC done — re-run `customize-ui` for new session |
+| Applied from `survey-ui-config.json` while still seed | Use `.final.json` or run `confirm-ui-config` after apply |
+| Only changed primary color, ignored diff | Read **entire** `diff.md` — clients often change 20+ paths |
+| Skipped `confirm-ui-config` | Active JSON stays seed; next wizard re-open is wrong |
+| Changed `Question.tsx` dispatch during apply | UI tokens only — see `apply-ui-config.md` scope |
+| Proceeded to deploy before apply | Complete Phase 6c first |
+| Logo works in wizard but broken on CloudFront | Preview uses memory; deploy needs `public/` → `out/` → S3 — see `aws-deploy.md` § Logos |
+| Used `global.logo.url` as Header src | Use `./{fileName}` only; download assets URL via `confirm-ui-config` |
+
+---
+
+## Related docs
+
+| Doc | Role |
+|-----|------|
+| [`apply-ui-config.md`](apply-ui-config.md) | Complete config path → file mapping |
+| [`wizard-api.md`](wizard-api.md) | Poll endpoint, complete payload |
+| [`wizard-question-type-styling.md`](wizard-question-type-styling.md) | Per-type CSS vars |
+| [`agent-operating-contract.md`](agent-operating-contract.md) | Anti-hallucination gates |