@explorer02/cfm-survey-sdk 0.2.3 → 0.2.5

package/templates/AGENT.md

@@ -1,11 +1,24 @@
 You are an AI coding agent tasked with building a survey UI using the CFM Survey SDK.
 
-## Start Here
+## Start Here (read in order — do not skip)
 
-**Monorepo:** read `packages/sdk/templates/docs/index.md`  
-**Installed package:** read `node_modules/@explorer02/cfm-survey-sdk/templates/docs/index.md`
+1. **`docs/00-integration/agent-operating-contract.md`** — anti-hallucination rules, read-before-write gates, forbidden inventions
+2. **`docs/00-integration/agent-execution-flow.md`** — pipeline, client questions, phase order
+3. **`docs/index.md`** — phase summary and artifact list
+4. **`docs/MANIFEST.json`** — machine-readable phase + question-type routing
 
-Also read `MANIFEST.json` in the same `templates/docs/` folder for machine-readable phase and question-type routing.
+**Monorepo:** `packages/sdk/templates/docs/`  
+**Installed package:** `node_modules/@explorer02/cfm-survey-sdk/templates/docs/`
+
+## Anti-hallucination (summary)
+
+- **If it's not in the docs or `docs/templates/`, do not implement it from memory.**
+- **Read before write** — complete the phase gate reads in `agent-operating-contract.md` §2 before any code.
+- **Copy templates first** — `Question.tsx`, scales, `selectionStyles.ts`, `labelStyles.ts`, `survey-theme.css`.
+- **Forbidden:** `apps/client`, SDK `/src/` imports, `subType`, stub branches, guessing answer shapes.
+- **Verify before handoff** — `bash templates/verify-agent-build.sh` must pass.
+
+Full blocklist and doc routing table: `agent-operating-contract.md`.
 
 ## Package Name
 
@@ -13,31 +26,59 @@ Import from whatever appears in `package.json`:
 - `@explorer02/cfm-survey-sdk` (npm)
 - `@repo/sdk` (monorepo)
 
+## Four client inputs
+
+| # | When | Ask |
+|---|------|-----|
+| 1 | Start | *(Client prompt — usually given)* |
+| 2 | Phase 2 | *"Please provide your survey instance ID (JWT token)."* |
+| 3 | Phase 6 | *"Your survey is running locally. Would you like to customize the UI through the web wizard?"* |
+| 4 | Phase 7 | *"Your survey is built and verified. Ready to deploy to production?"* |
+
 ## Phase Summary
 
 | Phase | Action |
 |-------|--------|
-| 0 | Detect framework; extract branding from client prompt |
-| 1 | Scaffold React app — `00-integration/setup.md` |
-| 2 | Ask client for instanceId JWT |
-| 3 | Read `client-integration-guide.md` + `question-type-sdk-matrix.md` + hook/logic/lifecycle/analytics docs — full SDK contract |
-| 4 | Fetch survey; inventory types; read MANIFEST-driven docs per type; copy `templates/Question.tsx` + scale templates + `implementation_plan.md` |
-| 5 | Build UI — copy templates from `docs/templates/`; read ui-spec Implementation Recipes; dispatch on **11** flat `QUESTION_TYPE` literals |
-| 6 | Run `templates/verify-agent-build.sh` |
-| 7 | On confirmation: **AWS prompt** → `aws-deploy.md`; **Vercel prompt** → `npx cfm-sdk deploy` |
+| 0 | Orient — read operating contract + execution flow; **UI-only** mockup notes (`mockup-ui-extraction.md`); detect framework |
+| 1 | Scaffold — `00-integration/setup.md` |
+| 2 | Ask JWT — `useSurveySDK.md` |
+| 3 | SDK contract — `client-integration-guide.md` + logic/lifecycle docs |
+| 4 | Plan — fetch survey, inventory types **from API**, placeholders + custom fields, copy `Question.tsx` + `implementation_plan.md` |
+| 5 | **Build wizard-ready UI** — read per-type `03-ui-specs/*` for every inventory type |
+| 6 | Verify — `verify-agent-build.sh`; start dev server; **ask wizard (INPUT 3)** |
+| 6b | Optional — **`npx cfm-sdk customize`** (default when client says yes); `customize-ui` only for remote client |
+| 6c | Apply every path from `survey-ui-config.final.json` → `confirm-ui-config` → re-verify |
+| 7 | Deploy — on confirmation per prompt or `deploy.target` |
+
+**Wizard run is optional. Wizard-ready build is mandatory in Phase 5.**
+
+**Do NOT** run the wizard before the survey UI is built. **Do NOT** read legacy `survey-config.json`. **Do NOT** use `apps/client` as implementation source.
+
+## Phase 5 required artifacts
+
+| Source (`docs/templates/`) | Destination |
+|----------------------------|-------------|
+| `survey-theme.css` | `src/styles/survey-theme.css` |
+| `selectionStyles.ts` | `src/lib/surveyUi/selectionStyles.ts` |
+| `labelStyles.ts` | `src/lib/surveyUi/labelStyles.ts` |
+| `previewBridge.ts` | `src/lib/previewBridge.ts` |
+| Scale components per inventory | `src/components/` |
+| Draft config | `./survey-ui-config.json` |
+
+Read: `wizard-preview-build-guide.md`, `wizard-question-type-styling.md`, per-type `03-ui-specs/*` (one per fetched type).
 
-**Do NOT** run `cfm-sdk init`, read `survey-config.json`, or use any setup wizard.
+**Selection pattern:** focus ring = outer border + inner dot; cell selected = annulus fill between ring and dot.
 
-**Do NOT** render `"not yet implemented"` or default fallback stubs in `Question.tsx`. Copy `templates/docs/templates/Question.tsx` and create all required scale components.
+**Do NOT** render `"not yet implemented"` or default fallback stubs in `Question.tsx`. Dispatch all **11** flat `QUESTION_TYPE` literals — no `subType`.
 
-**Copy scale templates from `docs/templates/`** before implementing from ui-spec recipes: `RankOrderScale.tsx`, `MatrixDropdown.tsx`, `CustomSliderTrack.tsx`, `surveyUiIcons.tsx`, `heatmapCoords.ts`.
+**Copy scale templates:** `SliderMatrixScale`, `LikertMatrixScale`, `CsatMatrixScale`, `RatingScale`, `FileUploadScale`, `HeatmapScale`, `RankOrderScale`, `MatrixDropdown`, `CustomSliderTrack`, `surveyUiIcons`, `surveyUiScaleUtils`, `heatmapCoords`, `customFieldValues` (when needed).
 
-**Do NOT** route matrix questions by `subType` — use flat types: `CFM_MATRIX`, `CSAT_MATRIX`, `RATING_MATRIX`, `SLIDER_MATRIX`.
+**Custom field logic:** when survey references `entityType: 'CUSTOM_FIELD'`, copy `customFieldValues.ts` and wire in hook options **and** `<Question customFieldValues={...} />`.
 
-**Read `question-type-sdk-matrix.md` before building any scale component** — it defines answer shapes, visibility helpers, and performance expectations for all 11 types.
+**Matrix types:** copy `LikertMatrixScale` / `CsatMatrixScale` — never bare radio grids without statement + label rows.
 
-**FILE_UPLOAD:** wire presigned upload per `00-integration/file-upload-aws.md` — raw `File[]` does not submit.
+**FILE_UPLOAD:** presigned upload per `file-upload-aws.md` — raw `File[]` does not submit.
 
 **Monorepo:** run `npm run build` in `packages/sdk` before starting the client dev server.
 
-Follow the master index strictly. Do not guess SDK internals. Do not import from `/src/` paths.
+Follow `agent-operating-contract.md` and `agent-execution-flow.md` strictly. Do not guess SDK internals. Do not import from `/src/` paths.

package/templates/deploy-wizard-to-s3.sh

@@ -0,0 +1,52 @@
+#!/usr/bin/env bash
+# Deploy survey-wizard SPA to S3 sites/_wizard/ on the hosting bucket.
+# Usage (from repo root):
+#   export HOSTING_BUCKET=... CLOUDFRONT_BASE_URL=... CLOUDFRONT_DISTRIBUTION_ID=...
+#   export VITE_WIZARD_API_BASE=http://43.204.26.213:3000
+#   bash packages/sdk/templates/deploy-wizard-to-s3.sh
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/../../.." && pwd)"
+
+: "${HOSTING_BUCKET:?HOSTING_BUCKET required}"
+: "${CLOUDFRONT_BASE_URL:?CLOUDFRONT_BASE_URL required}"
+: "${AWS_REGION:=ap-south-1}"
+: "${VITE_WIZARD_API_BASE:?VITE_WIZARD_API_BASE required for production wizard build}"
+
+WIZARD_PREFIX="${WIZARD_S3_PREFIX:-sites/_wizard}"
+CF_BASE="${CLOUDFRONT_BASE_URL%/}"
+
+echo "Building survey-wizard (VITE_WIZARD_API_BASE=$VITE_WIZARD_API_BASE)..."
+cd "$REPO_ROOT"
+VITE_WIZARD_API_BASE="$VITE_WIZARD_API_BASE" yarn workspace @repo/survey-wizard build
+
+DIST="$REPO_ROOT/packages/sdk/templates/wizard-dist"
+
+if [ ! -d "$DIST" ]; then
+  echo "wizard-dist not found at $DIST"
+  exit 1
+fi
+
+echo "Uploading to s3://${HOSTING_BUCKET}/${WIZARD_PREFIX}/"
+aws s3 sync "$DIST/" "s3://${HOSTING_BUCKET}/${WIZARD_PREFIX}/" \
+  --region "$AWS_REGION" \
+  --delete \
+  --cache-control "public,max-age=300"
+
+if [ -n "${CLOUDFRONT_DISTRIBUTION_ID:-}" ]; then
+  echo "Invalidating CloudFront /${WIZARD_PREFIX}/* ..."
+  aws cloudfront create-invalidation \
+    --distribution-id "$CLOUDFRONT_DISTRIBUTION_ID" \
+    --paths "/${WIZARD_PREFIX}/*" \
+    --query 'Invalidation.Id' \
+    --output text
+else
+  echo "CLOUDFRONT_DISTRIBUTION_ID not set — skip invalidation"
+fi
+
+echo ""
+echo "Done. Wizard URLs:"
+echo "  CloudFront (static UI): ${CF_BASE}/${WIZARD_PREFIX}/index.html"
+echo "  EC2 session (customize-ui opens this): http://43.204.26.213:3000/wizard-app/index.html"

package/templates/docs/00-integration/agent-execution-flow.md

@@ -0,0 +1,293 @@
+# Agent Execution Flow
+
+> **Read first:** [`agent-operating-contract.md`](agent-operating-contract.md) (anti-hallucination), then this file with [`index.md`](../index.md).  
+> This doc defines the **only** approved agent workflow: what to read, what to ask the client, and what to execute — in order.
+
+Machine-readable routing: [`MANIFEST.json`](../MANIFEST.json) `phases[]`.
+
+---
+
+## Golden rules
+
+0. **Operating contract** — follow [`agent-operating-contract.md`](agent-operating-contract.md): read-before-write gates, doc routing table, hallucination blocklist.
+1. **Docs-first** — never guess SDK behavior; read MANIFEST-routed docs before writing code.
+2. **Four client inputs only** — prompt (given), instanceId (ask), wizard yes/no (ask), deploy yes/no (ask).
+3. **Build before wizard** — survey UI must run on localhost before Phase 6b.
+4. **UI-only wizard** — wizard changes tokens and chrome text, never dispatch logic or answer shapes.
+5. **No stubs** — zero `"not yet implemented"` branches; dispatch all **11** `question.type` literals.
+6. **Flat types** — no `subType`; route `CFM_MATRIX`, `CSAT_MATRIX`, `RATING_MATRIX`, `SLIDER_MATRIX` separately.
+7. **Copy templates** — scale components from `docs/templates/`; extend, do not rewrite from scratch.
+8. **Wizard-ready in Phase 5** — always wire `survey-theme.css`, `selectionStyles.ts`, `labelStyles.ts`, and `data-cfm-*` hooks even if client skips the wizard later.
+
+---
+
+## Client inputs — exact questions
+
+| # | When | Agent asks (verbatim intent) | On answer |
+|---|------|------------------------------|-----------|
+| **1** | Start (usually given) | *(Client prompt — mockup, brand, deploy target hints)* | UI-only notes per `mockup-ui-extraction.md`; **not** survey structure |
+| **2** | Phase 2 | *"Please provide your survey instance ID (JWT token)."* | Store as `CFM_INSTANCE_ID` / `SURVEY_INSTANCE_ID`; fetch survey |
+| **3** | Phase 6 (after verify + dev server) | *"Your survey is running locally. Would you like to customize the UI through the web wizard?"* | **Yes** → Phase 6b. **No** → Phase 7 ask |
+| **4** | Phase 7 | *"Your survey is built and verified. Ready to deploy to production?"* | **Yes** → deploy per prompt/config. **No** → stop |
+
+**Do not ask** about wizard before Phase 6. **Do not run** `customize-ui` before build + verify.
+
+---
+
+## Phase-by-phase execution
+
+### Phase 0 — Orient
+
+**Read:** `agent-operating-contract.md`, `index.md`, `AGENT.md`, `agent-execution-flow.md`, `MANIFEST.json` (skim `phases`, `typeLiterals`, `questionTypes`)
+
+**Do:**
+- Detect framework from `package.json` → `setup.md`
+- Extract **UI-only** from mockup/prompt per [`mockup-ui-extraction.md`](mockup-ui-extraction.md) — colors, chrome, header/footer format, display copy
+- Do **not** infer question types, language, or logic from mockup
+
+---
+
+### Phase 1 — Scaffold
+
+**Read:** `00-integration/setup.md` (framework section)
+
+**Do:**
+- Install `@explorer02/cfm-survey-sdk` (or `@repo/sdk`), `@tanstack/react-query`, `react-icons`
+- Apply AWS static export config **now** if prompt mentions AWS/CloudFront/S3/EC2/Sprinklr
+
+---
+
+### Phase 2 — Instance ID (INPUT 2)
+
+**Read:** `00-integration/useSurveySDK.md`
+
+**Ask:** JWT token (see table above)
+
+**Do:**
+- Wire `instanceId` in `SurveyPage` / hook options
+- Do **not** build question UI yet
+
+---
+
+### Phase 3 — SDK contract
+
+**Read (in order):**
+1. `00-integration/client-integration-guide.md`
+2. `00-integration/question-type-sdk-matrix.md`
+3. `00-integration/useSurveySDK.md`
+4. `00-integration/client-lib-folder.md`
+5. `00-integration/custom-field-logic-and-navigation.md`
+6. `00-integration/skip-logic-and-navigation.md`
+7. `00-integration/display-logic-and-navigation.md`
+8. `00-integration/placeholders-and-tokens.md`
+9. `00-integration/survey-lifecycle-analytics.md`
+10. `02-reference/exports.md`, `02-reference/value-derivation.md`
+
+**Do:**
+- Understand `onAction`, `state.answers`, visibility helpers, lifecycle actions
+- **Forbidden:** imports from `.../src/...` inside the SDK package
+
+---
+
+### Phase 4 — Plan + ingest
+
+**Read (always):**
+- `component-checklist.md`, `canonical-survey-fixtures.md`, `logic-fields-catalog.md`
+- `03-ui-specs/00-question-shell.md`, `03-ui-specs/12-survey-chrome.md`
+- `01-components/01-survey-page.md`, `01-components/02-question.md`
+- `01-components/14-intro-page.md`, `01-components/15-end-page.md`, `01-components/16-paused-page.md`
+
+**Read (per fetched survey type):** MANIFEST `questionTypes.{type}` → `blueprint` + `reference` + `uiSpec`
+
+**Read (when flags match):** MANIFEST `sharedUiSpecTriggers` → `03-ui-specs/shared/*`
+
+**Do:**
+1. Fetch survey with instanceId
+2. List unique `question.type` values in `implementation_plan.md` §3b (**from fetch only**)
+3. Scan placeholders + `_c_…` custom fields per [`placeholders-and-custom-fields-wiring.md`](placeholders-and-custom-fields-wiring.md)
+4. Copy `templates/implementation_plan.md` → project root; fill all sections
+4. Copy `templates/Question.tsx` as dispatcher starting point
+5. **Auto-proceed to Phase 5** — no approval wait
+
+---
+
+### Phase 5 — Build (wizard-ready)
+
+**Read:**
+- `00-integration/constraints.md`
+- `00-integration/component-checklist.md`
+- `00-integration/wizard-preview-build-guide.md` **(required)**
+- `00-integration/wizard-question-type-styling.md` **(required)**
+- `00-integration/question-type-sdk-matrix.md`
+- Per-type `03-ui-specs/*` from inventory
+
+**Copy to project (required artifacts):**
+
+| Source (`docs/templates/`) | Destination |
+|----------------------------|-------------|
+| `survey-theme.css` | `src/styles/survey-theme.css` |
+| `selectionStyles.ts` | `src/lib/surveyUi/selectionStyles.ts` |
+| `labelStyles.ts` | `src/lib/surveyUi/labelStyles.ts` |
+| `previewBridge.ts` | `src/lib/previewBridge.ts` (local `customize` dev) |
+| Scale components per inventory | `src/components/` |
+| `surveyUiScaleUtils.ts`, `surveyUiIcons.tsx` | `src/lib/` |
+| `customFieldValues.ts` | `src/lib/` (when `_c_…` in survey logic) |
+
+**Wire in `globals.css`:**
+```css
+@import "./styles/survey-theme.css";
+```
+
+**Wire in root `layout.tsx`:** `<PreviewBridgeInit />` (see `wizard-preview-build-guide.md`)
+
+**Chrome contract (`data-cfm-*`):**
+- Header: `data-cfm-logo` and/or `data-cfm-logo-text`, `data-cfm-company`
+- SurveyPage: `data-cfm-btn-next`, `data-cfm-btn-back`
+- Intro/End: `data-cfm-survey-title`, `data-cfm-thank-you`
+- Footer: `data-cfm-copyright`, `data-cfm-footer-links`
+
+**Selection styling (all scale radios):** use `selectionStyles.ts` — see `wizard-question-type-styling.md`
+
+**Label items (matrices/sliders):** use `labelStyles.ts` — column headers are label items, not hint labels (CFM matrix)
+
+**Draft config:** write `./survey-ui-config.json` + keep CSS in sync (seeds wizard in 6b)
+
+**Forbidden in Phase 5:**
+- Changing `Question.tsx` dispatch / `onAction` payloads
+- `subType` routing
+- Stub placeholder branches
+- Hardcoded brand hex for wizard-controlled tokens
+
+**Auto-proceed to Phase 6** after build compiles.
+
+---
+
+### Phase 6 — Verify
+
+**Read:** `constraints.md` (troubleshooting)
+
+**Run:** `bash templates/verify-agent-build.sh`
+
+**Checklist:** see `index.md` Phase 6 + `component-checklist.md` Step 3–4
+
+**Do:**
+- `npm run build` → exit 0
+- Start dev server; confirm survey loads
+- **Ask INPUT 3** (wizard question)
+
+---
+
+### Phase 6b — Wizard session (optional, INPUT 3 = Yes)
+
+**Default:** `npx cfm-sdk customize` — local wizard on `localhost:4200`. Best for preview smoothness, direct JSON save, and automatic cleanup.
+
+**EC2 fallback:** `customize-ui` — only when client customizes from **another device**.
+
+**Read:** `ui-customization-wizard.md`, `wizard-preview-build-guide.md`, `wizard-troubleshooting.md`, `apply-ui-config.md`
+
+**Prerequisites:** Phase 6 passed; draft `survey-ui-config.json` exists
+
+**Run (default — agent blocks until client saves):**
+```bash
+npx cfm-sdk customize
+```
+
+**Sequence:**
+1. CLI auto-exports all 11 component previews to `out/previews/`
+2. Opens wizard at `http://localhost:4200`
+3. Client customizes (same machine as agent); live iframes from local previews
+4. Client clicks **Review & Build** → `survey-ui-config.json` written
+5. CLI exits 0 → agent applies per Phase 6c
+
+**Tell the client:** *"Complete the wizard in the browser that just opened and click **Review & Build**."*
+
+**Remote client only:**
+```bash
+export CFM_INSTANCE_ID="<JWT>"
+export CFM_DEPLOY_API_BASE="http://43.204.26.213:3000"
+npx cfm-sdk customize-ui
+```
+Share EC2 link; keep CLI open until `✅ Configuration ready`. See `wizard-config-handoff.md`.
+
+**If client said No:** skip to Phase 7 ask.
+
+---
+
+### Phase 6c — Apply wizard changes (mandatory when wizard used)
+
+**Read:** `wizard-config-handoff.md`, `apply-ui-config.md`, `wizard-question-type-styling.md`
+
+**Input file:**
+- AWS: `survey-ui-config.final.json`
+- Local: `survey-ui-config.json`
+
+**Do (in order):**
+1. Validate JSON against `templates/survey-ui-config.schema.json`
+2. Read **entire** `survey-ui-config.diff.md` (AWS) — every path must be applied
+3. Regenerate `src/styles/survey-theme.css` from **full** final config (not partial)
+4. Update all `data-cfm-*` content hooks (title, buttons, footer, logo)
+5. Apply layout toggles in `SurveyPage` / chrome
+6. Wire `placeholders`, `customFields`, `debug` from final config
+7. Apply per-type `questionTypes.*` for every type in `surveyTypes[]`
+8. AWS: `npx cfm-sdk confirm-ui-config` (promotes final → active + downloads logo)
+9. When `global.logo.fileName` is set: update `Header.tsx` `data-cfm-logo src="./{fileName}"`; verify `public/{fileName}` exists
+10. Re-run `verify-agent-build.sh` + `npm run build`
+11. Verify logo in static output: `test -f out/$(jq -r '.global.logo.fileName' survey-ui-config.json)` when fileName set
+12. **Do not** change dispatch logic in `Question.tsx`
+
+**Blocking:** Do not proceed to Phase 7 until diff paths are applied and verify passes.
+
+---
+
+### Phase 7 — Deploy (INPUT 4)
+
+**Ask:** deploy confirmation (see table)
+
+**Before AWS deploy (when wizard set a logo):**
+
+```bash
+LOGO=$(python3 -c "import json; print(json.load(open('survey-ui-config.json')).get('global',{}).get('logo',{}).get('fileName') or '')")
+test -z "$LOGO" || test -f "out/$LOGO" || { echo "Logo missing from out/ — fix Phase 6c Header + public/"; exit 1; }
+```
+
+See [`aws-deploy.md`](aws-deploy.md) § Logos & local assets.
+
+**Route:**
+- AWS keywords in prompt → `aws-deploy.md` + `deploy-to-aws.sh`
+- Else / Vercel → `npx cfm-sdk deploy`
+- Override with `survey-ui-config.json` → `deploy.target` when present
+
+---
+
+## Wizard styling quick reference
+
+| Wizard control | CSS variable | Component pattern |
+|----------------|--------------|-------------------|
+| Question card → Cell selected | `--cfm-matrix-selected` | Annulus fill between ring and dot; numbered/star cell bg |
+| Question card → Focus ring | `--cfm-input-focus-ring` | Outer radio border + inner dot |
+| Matrix label items | `--cfm-matrix-column-label-*` | `matrixColumnLabelStyle()` |
+| CSAT label items | `--cfm-csat-column-label-*` | `csatColumnLabelStyle()` |
+| Hint labels (NPS min/max) | `--cfm-hint-label-*` | `hintLabelStyle()` |
+| Number labels (traffic/mono/individual) | `--cfm-number-*` | `resolveNumberLabelColor()` in scale utils |
+| File upload border | `--cfm-upload-border-color` | Dropzone border |
+| MCQ selection | focus ring + cell selected | Radio ring/dot pattern |
+
+Full mapping: [`wizard-question-type-styling.md`](wizard-question-type-styling.md)
+
+---
+
+## Doc index by task
+
+| Task | Read |
+|------|------|
+| Anti-hallucination / doc routing | `agent-operating-contract.md` |
+| Full pipeline | `agent-operating-contract.md` + this file + `index.md` |
+| Hook / answers | `client-integration-guide.md`, `useSurveySDK.md` |
+| Copy files list | `component-checklist.md`, `client-lib-folder.md` |
+| Matrix labels | `canonical-survey-fixtures.md` |
+| Wizard chrome | `wizard-preview-build-guide.md` |
+| Wizard per-type | `wizard-question-type-styling.md` |
+| Wait + capture + apply order | `wizard-config-handoff.md` |
+| Apply every config path | `apply-ui-config.md` |
+| Logo rules | `constraints.md` §4, `10-header-footer.md` |
+| UI spec details | `03-ui-specs/{type}.md` per inventory |