Web app refactoring prompt (Cursor)

Use this page with Prego Web App Standard and Web app standardization plan. Before new public HTTP behavior, also follow How to add an API and API gateway & BFF governance.

When to use

Refactoring apps/www, apps/admin-web, or apps/client-web
Extracting shared UI, forms, or Zod contracts
Moving legacy/demo assets to archive/
Aligning validation (RHF + Zod) without changing product behavior unsafely

Verify commands after web app changes

Run from the Prego repo root unless you are only inside one app’s package.json scripts.

App	Typical command	Notes
client-web	`pnpm run verify:client-web:quick` or `pnpm run verify:client-web`	Quick = app `verify` (lint, typecheck, Vitest `test:unit`, dictionaries). Full `verify:client-web` adds production `next build`. See `apps/client-web/AGENTS.md`. If `dictionaries/en.json` changed: `pnpm run dictionaries:sync`. From repo root: `pnpm run test:unit:client-web` / `pnpm run test:unit:client-web:watch` (same as app `test:unit` / `test:unit:watch`).
www	`pnpm run verify:www` (root) or `pnpm run verify` under `apps/www`	Full static pipeline: `pnpm run pages:build:www` (marketing, trial copy, Pages functions, build).
admin-web	Follow `apps/admin-web/README.md` and root admin-web notes in `AGENTS.md`	E2E: `pnpm run test:e2e:admin-web` when flows change.
Monorepo (`@platform/next-dev-scripts`)	`pnpm run verify:next-dev-scripts`	Run when editing `packages/prego-next-dev-scripts` or www / admin-web / client-web `package.json` scripts that invoke `prego-strip-next-dev-types-from-tsconfig`. Also covered by root `pnpm run build:verify`. CI: `.github/workflows/next-dev-scripts.yml`. Full workflow map: `.github/workflows/README.md`.
Monorepo (Starlight `docs`)	`pnpm run build:docs` or `pnpm run build:verify`	Internal docs under `docs/` are MDX — `docs/README.md` · Dependency inspection §7. If `astro build` fails with missing chunks under `docs/dist` (e.g. `renderers.mjs`), from repo root run `pnpm run build:docs:clean` — `AGENTS.md`. Dependency inspection §8.

client-web — Assistant UI (app/my-ai/): Import @/app/my-ai/page-controller only from app/my-ai/page.tsx or under app/my-ai/page-controller/ (barrel + tests). Other app/my-ai/** modules use concrete build-my-ai-page-controller-*.ts paths — ESLint no-restricted-imports in eslint.config.mjs (avoids a circular dependency with useMyAiPageController). See apps/client-web/AGENTS.md.

client-web — passcode keypad & verify-email OTP: Routes that fetch Auth Worker /auth/verify, /auth/passcode/*, or /auth/otp/verify (e.g. auth/verify-email) must call parsePasscodePin / parsePasscodePinFromInput / takeLeadingDigits from lib/schemas/passcode-pin.ts as appropriate (same six-digit rule as otpCodeSchema); keypad components default pinLength from PASSCODE_PIN_LENGTH in that module; keypad UX is not RHF. See apps/client-web/AGENTS.md and Dependency inspection §8.

Docs only: cd docs && pnpm run build (or repo root pnpm run build:docs). MDX: docs/README.md. Missing chunk errors (e.g. renderers.mjs): pnpm run build:docs:clean — AGENTS.md.

Prompt A — Scoped refactor (single PR)

Copy and fill {APP}, {SCOPE}:

You are working in the Prego monorepo on web app `{APP}` only (one of: www, admin-web, client-web).

Mandatory context (read in-repo paths if present):
- docs/src/content/docs/platform/prego-web-app-standard.md
- docs/src/content/docs/platform/api-bff-governance.md
- https://github.com/Pregoi/prego_ai/blob/main/docs/from-prego-monorepo/platform/dependency-inspection-for-ai.md
- If the task touches **client-web** **`app/my-ai/`**: **apps/client-web/AGENTS.md** (Assistant UI section) — **`@/app/my-ai/page-controller`** imports are ESLint-gated (**eslint.config.mjs**); orchestration modules use concrete **`build-my-ai-page-controller-*.ts`** paths.

Scope: {SCOPE}

Rules:
1. Do not add ERP/domain business rules in Next — Frappe owns ERP; Workers own edge/API orchestration per repo matrix.
2. Default public/browser APIs go through Zuplo; thin same-origin BFF only per api-bff-governance (cookies, secrets, presigned uploads, Pages Functions where listed).
3. Forms: prefer React Hook Form + Zod; no parallel ad hoc validation stacks for the same flow.
4. Extract duplicates to packages/* (ui, forms, contracts, api-client) when it removes real duplication; avoid speculative abstractions.
5. No new undocumented HTTP contracts — if behavior is user-visible and crosses the gateway, OpenAPI in prego-zuplo first (see how-to-add-api).
6. Move non-canonical legacy/demo files to archive/ with a short README note if you touch that area.
7. Keep the diff minimal: only what the scope requires; run the app’s documented verify/lint commands if you change code.

Deliver: concise summary of files changed, any follow-up for OpenAPI or other repos.

Prompt A — Filled examples (ready to paste)

Replace nothing — these are complete scopes. Adjust folder names if your tree differs.

Example 1 — admin-web (onboarding step validation)

You are working in the Prego monorepo on web app `admin-web` only.

Mandatory context (read in-repo paths if present):
- docs/src/content/docs/platform/prego-web-app-standard.md
- docs/src/content/docs/platform/api-bff-governance.md
- https://github.com/Pregoi/prego_ai/blob/main/docs/from-prego-monorepo/platform/dependency-inspection-for-ai.md

Scope: One onboarding step (pick the step the user is editing): replace ad hoc validation with React Hook Form + Zod for that step’s form only. Do not change Zuplo URLs or env vars. If a field matches an existing Zod schema elsewhere in the monorepo, import or propose a shared schema in `packages/*` only if duplication is clear.

Rules:
1. Do not add ERP/domain business rules in Next — Frappe owns ERP; Workers own edge/API orchestration per repo matrix.
2. Default public/browser APIs go through Zuplo; thin same-origin BFF only per api-bff-governance (cookies, secrets, presigned uploads, Pages Functions where listed).
3. Forms: prefer React Hook Form + Zod; no parallel ad hoc validation stacks for the same flow.
4. Extract duplicates to packages/* (ui, forms, contracts, api-client) when it removes real duplication; avoid speculative abstractions.
5. No new undocumented HTTP contracts — if behavior is user-visible and crosses the gateway, OpenAPI in prego-zuplo first (see how-to-add-api).
6. Move non-canonical legacy/demo files to archive/ with a short README note if you touch that area.
7. Keep the diff minimal: only what the scope requires; run the app’s documented verify/lint commands if you change code.

Deliver: concise summary of files changed, any follow-up for OpenAPI or other repos.

Example 2 — client-web (shared contract extraction)

You are working in the Prego monorepo on web app `client-web` only.

Mandatory context (read in-repo paths if present):
- docs/src/content/docs/platform/prego-web-app-standard.md
- docs/src/content/docs/platform/api-bff-governance.md
- https://github.com/Pregoi/prego_ai/blob/main/docs/from-prego-monorepo/platform/dependency-inspection-for-ai.md

Scope: Extract duplicated Zod request/response shapes used for Zuplo-facing `fetch` calls in one feature area into a single module under `packages/` (or the repo’s existing contracts package) and update imports. Do not change runtime API behavior or URLs.

Rules:
1. Do not add ERP/domain business rules in Next — Frappe owns ERP; Workers own edge/API orchestration per repo matrix.
2. Default public/browser APIs go through Zuplo; thin same-origin BFF only per api-bff-governance (cookies, secrets, presigned uploads, Pages Functions where listed).
3. Forms: prefer React Hook Form + Zod; no parallel ad hoc validation stacks for the same flow.
4. Extract duplicates to packages/* (ui, forms, contracts, api-client) when it removes real duplication; avoid speculative abstractions.
5. No new undocumented HTTP contracts — if behavior is user-visible and crosses the gateway, OpenAPI in prego-zuplo first (see how-to-add-api).
6. Move non-canonical legacy/demo files to archive/ with a short README note if you touch that area.
7. Keep the diff minimal: only what the scope requires; run the app’s documented verify/lint commands if you change code.

Deliver: concise summary of files changed, any follow-up for OpenAPI or other repos.

Example 3 — www (marketing / trial UI only)

You are working in the Prego monorepo on web app `www` only.

Mandatory context (read in-repo paths if present):
- docs/src/content/docs/platform/prego-web-app-standard.md
- docs/src/content/docs/platform/api-bff-governance.md
- https://github.com/Pregoi/prego_ai/blob/main/docs/from-prego-monorepo/platform/dependency-inspection-for-ai.md

Scope: Refactor one trial or marketing page component for clarity and a11y; keep browser calls pointing at Zuplo via `NEXT_PUBLIC_ZUPLO_API_URL` as today. Do not add new API routes in www unless they match existing Pages Functions patterns in api-bff-governance.

Rules:
1. Do not add ERP/domain business rules in Next — Frappe owns ERP; Workers own edge/API orchestration per repo matrix.
2. Default public/browser APIs go through Zuplo; thin same-origin BFF only per api-bff-governance (cookies, secrets, presigned uploads, Pages Functions where listed).
3. Forms: prefer React Hook Form + Zod; no parallel ad hoc validation stacks for the same flow.
4. Extract duplicates to packages/* (ui, forms, contracts, api-client) when it removes real duplication; avoid speculative abstractions.
5. No new undocumented HTTP contracts — if behavior is user-visible and crosses the gateway, OpenAPI in prego-zuplo first (see how-to-add-api).
6. Move non-canonical legacy/demo files to archive/ with a short README note if you touch that area.
7. Keep the diff minimal: only what the scope requires; run the app’s documented verify/lint commands if you change code.

Deliver: concise summary of files changed, any follow-up for OpenAPI or other repos.

Example 4 — client-web (Assistant UI /my-ai orchestration)

You are working in the Prego monorepo on web app `client-web` only.

Mandatory context (read in-repo paths if present):
- docs/src/content/docs/platform/prego-web-app-standard.md
- docs/src/content/docs/platform/api-bff-governance.md
- https://github.com/Pregoi/prego_ai/blob/main/docs/from-prego-monorepo/platform/dependency-inspection-for-ai.md
- apps/client-web/AGENTS.md (Assistant UI section — page-controller barrel, ESLint)

Scope: Refactor or extend wiring under `app/my-ai/` without changing product behavior; keep hooks and param builders aligned with the existing page-controller pipeline.

Rules:
1. Do not add ERP/domain business rules in Next — Frappe owns ERP; Workers own edge/API orchestration per repo matrix.
2. Default public/browser APIs go through Zuplo; thin same-origin BFF only per api-bff-governance (cookies, secrets, presigned uploads, Pages Functions where listed).
3. Forms: prefer React Hook Form + Zod; no parallel ad hoc validation stacks for the same flow.
4. Extract duplicates to packages/* (ui, forms, contracts, api-client) when it removes real duplication; avoid speculative abstractions.
5. No new undocumented HTTP contracts — if behavior is user-visible and crosses the gateway, OpenAPI in prego-zuplo first (see how-to-add-api).
6. Move non-canonical legacy/demo files to archive/ with a short README note if you touch that area.
7. **Assistant UI:** import **`@/app/my-ai/page-controller`** only from **`app/my-ai/page.tsx`** or **`app/my-ai/page-controller/**`**; other **`app/my-ai/**`** files use concrete **`build-my-ai-page-controller-*.ts`** / **`use-my-ai-*.ts`** modules (see **AGENTS.md**, **eslint.config.mjs**).
8. Keep the diff minimal: only what the scope requires; run **`pnpm run verify`** (includes Vitest **`test:unit`**) if you change code.

Deliver: concise summary of files changed, any follow-up for OpenAPI or other repos.

Prompt B — Admin-web contract hardening (Zod / forms)

Focus: apps/admin-web — onboarding, billing, auth handoff, tenant/plan/region, provisioning inputs.

Read:
- docs/src/content/docs/platform/prego-web-app-standard.md (§3, §6)
- docs/src/content/docs/platform/api-bff-governance.md (admin-web row)

Goal: Introduce or strengthen RHF + Zod on the targeted flow only; share schemas via packages/contracts when the same shape exists in client-web or should be reused.

Do not: call /internal/* from the browser; duplicate gateway routes in Next; widen scope beyond the specified screens/components.

After edits: list which env vars and Zuplo bases unchanged; note if prego-zuplo OpenAPI needs updates (separate repo task).

Prompt B — Filled example (billing or plan UI only)

Focus: apps/admin-web — onboarding, billing, auth handoff, tenant/plan/region, provisioning inputs.

Read:
- docs/src/content/docs/platform/prego-web-app-standard.md (§3, §6)
- docs/src/content/docs/platform/api-bff-governance.md (admin-web row)

Goal: On the Stripe/billing-related screen I am editing (same folder as the open file), introduce RHF + Zod for the visible form fields only. Reuse or create a Zod schema in packages/contracts only if an identical shape already exists elsewhere; otherwise keep schema next to the form for this PR. Do not change redirect URLs or env vars.

Do not: call /internal/* from the browser; duplicate gateway routes in Next; widen scope beyond the specified screens/components.

After edits: list which env vars and Zuplo bases unchanged; note if prego-zuplo OpenAPI needs updates (separate repo task).

Prompt C — Legacy / archive sweep

Goal: Identify HTML, demos, or duplicate “reference” UIs that are not the canonical Next implementation for admin-web or www.

Read:
- docs/src/content/docs/platform/prego-web-app-standard.md §13 (Refactoring rules)

Actions:
1. List candidate files/folders with one line each: canonical vs archive.
2. Propose moves to archive/legacy/... with README explaining “do not edit for production”.
3. Do not delete without explicit confirmation in the task; prefer move + README.
4. Update only README or agent-facing notes if needed so Cursor/IDE does not treat archive as active product code.

Prompt C — Filled example (`admin-web` only)

Goal: Identify HTML, demos, or duplicate “reference” UIs that are not the canonical Next implementation for admin-web or www.

Read:
- docs/src/content/docs/platform/prego-web-app-standard.md §13 (Refactoring rules)
- apps/admin-web/README.md (what is canonical vs legacy)

Actions:
1. List candidate files/folders under apps/admin-web with one line each: canonical vs archive.
2. Propose moves to apps/admin-web/archive/legacy/... with a short README: “not production; do not edit for features”.
3. Do not delete without explicit confirmation in the task; prefer move + README.
4. If README or AGENTS.md should mention the archive path for agents, add one sentence only.

Limit scope to apps/admin-web; do not touch prego-control-plane in this task unless the user explicitly includes it.

Prompt D — Cross-repo API (gateway / Worker)

Use when the refactor might need new or changed HTTP — run before coding the UI:

Stop: new public HTTP behavior requires contract-first order:
1. prego-zuplo OpenAPI fragment + sync-oas + verify
2. Zuplo route
3. Worker or Frappe handler

Read docs/src/content/docs/platform/how-to-add-api.md and dependency-inspection-for-ai.md.

If the change is only UI calling existing Zuplo-documented routes, stay in the monorepo and follow api-bff-governance for browser vs BFF.

Prompt D — Filled example (new public route — stop and plan)

Stop: I need a new browser-callable JSON endpoint for the product (not same-origin BFF).

New public HTTP behavior requires contract-first order:
1. prego-zuplo: add or extend OpenAPI fragment under config/*.oas.json, then repo root pnpm run sync-oas && pnpm run verify
2. Zuplo route + module forwarding to the correct Worker or upstream
3. Implement handler in prego-control-plane, prego_ai, or Frappe per repo-responsibility-matrix

Read docs/src/content/docs/platform/how-to-add-api.md and dependency-inspection-for-ai.md.

Do not implement the Next.js UI change until steps 1–3 are agreed and the operationId exists in merged OAS.

If the change is only UI calling existing Zuplo-documented routes, stay in the Prego monorepo and follow api-bff-governance for browser vs BFF — no prego-zuplo edit.

한국어

위 블록은 Cursor에 복사해 붙여 넣는 실행 프롬프트입니다. Prompt A — Filled examples 에는 admin-web · client-web (공유 계약 추출·Assistant UI /my-ai) · www 용 예시가 있고, Prompt B/C/D 에도 각각 채운 예시가 있습니다. 상단 Verify commands after web app changes 표로 리팩터 후 검증 명령을 맞추세요. 공개 API 변경이 있으면 prego-zuplo OpenAPI 선행과 BFF 거버넌스 를 반드시 함께 따르세요. 표준 본문은 Prego Web App Standard 입니다.