docs/features/frontend-infrastructure-hardening/plan.md

@@ -0,0 +1,120 @@
+# Frontend Infrastructure Hardening Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Stabilize frontend infrastructure and tooling so local development, contract freshness, and mock-based workflows are deterministic and do not rely on temporary compatibility layers.
+
+**Architecture:** This feature is a small set of related infrastructure follow-ups executed in a controlled order: mock-mode docs and wiring, env validation, tooling consistency, and contract freshness. Each step should leave the project in a working state and avoid changing user-facing runtime behavior except where the infrastructure itself must be activated.
+
+**Tech Stack:** Vite, MSW, Zod, Biome/ESLint, OpenAPI-generated types, existing frontend tooling scripts.
+
+---
+
+### Task 1: Browser mock mode wiring
+
+**Files:**
+- Create/Modify: `apps/frontend/mocks/browser.ts`
+- Modify: `apps/frontend/public/mockServiceWorker.js`
+- Modify: `apps/frontend/src/main.tsx`
+- Modify: `apps/frontend/src/shared/config/env.ts`
+- Modify: `apps/docs/docs/development/commands.md`
+- Modify: `apps/docs/docs/frontend/overview.md`
+
+- [ ] **Step 1: Add a browser MSW entry that reuses existing handlers**
+
+Ensure the browser worker uses the existing `apps/frontend/mocks/handlers.ts` instead of duplicating request logic.
+
+- [ ] **Step 2: Gate worker startup behind `VITE_API_MOCK`**
+
+Hook the browser mock startup into `main.tsx` so it activates only when the env flag explicitly asks for it.
+
+- [ ] **Step 3: Document the mock mode behavior**
+
+Document the developer-facing rule: mock mode is opt-in, backend-free dev is supported, and the default path still uses the real API.
+
+### Task 2: Env validation
+
+**Files:**
+- Modify: `apps/frontend/src/shared/config/env.ts`
+- Modify: `apps/frontend/src/main.tsx`
+- Test: any existing frontend startup/env tests, if present
+
+- [ ] **Step 1: Define the runtime env schema**
+
+Add a Zod schema for required `VITE_*` variables and keep optional values explicit.
+
+- [ ] **Step 2: Fail fast on invalid env**
+
+Call validation before app render so invalid configuration is visible at startup instead of failing later in a component or query path.
+
+- [ ] **Step 3: Verify startup messaging**
+
+Make sure the error path explains what is missing or invalid without leaking secrets.
+
+### Task 3: Tooling consistency
+
+**Files:**
+- Modify: `apps/frontend/package.json`
+- Modify: `apps/frontend/.eslintrc.cjs` or `apps/frontend/biome.json` if the project already has a replacement config
+- Modify: `.gitea/workflows/ci.yml` only if the current tooling commands need to be aligned
+- Modify: `apps/docs/docs/development/commands.md`
+
+- [ ] **Step 1: Verify the command set matches the current toolchain**
+
+Keep `lint`, `test`, `build`, and `codegen` aligned with the real frontend structure and remove stale command references.
+
+- [ ] **Step 2: Align lint/format docs with reality**
+
+Update documentation so it describes the actual commands developers run today, not an earlier migration stage.
+
+- [ ] **Step 3: Confirm no stale tooling references remain**
+
+Remove or rewrite mentions of dead scripts, obsolete shims, or incorrect setup instructions.
+
+### Task 4: Contract freshness
+
+**Files:**
+- Modify: `apps/frontend/src/shared/api/index.ts`
+- Modify: `apps/frontend/src/shared/api/types.ts` only through codegen, not manual edits
+- Modify: the specific frontend entity API files that still depend on stale wrapper assumptions
+- Modify: `apps/docs/docs/frontend/api-client.md`
+- Modify: `apps/docs/docs/frontend/overview.md`
+
+- [ ] **Step 1: Reconcile the frontend contract entrypoints**
+
+Ensure the shared API surface points to the actual generated contract types and current public API entrypoints.
+
+- [ ] **Step 2: Remove stale contract wording from docs**
+
+Document the current source of truth for API types and avoid references to temporary compatibility layers.
+
+- [ ] **Step 3: Verify generated types are treated as generated**
+
+Make sure the plan keeps `types.ts` as generated output and avoids manual editing patterns.
+
+### Task 5: Verification
+
+**Files:**
+- Read: changed docs and frontend tooling files
+
+- [ ] **Step 1: Run the targeted frontend checks**
+
+Run:
+
+```bash
+npm run lint -w apps/frontend
+npm run test -w apps/frontend
+npm run build -w apps/frontend
+```
+
+Expected: all three commands pass after the infra hardening changes land.
+
+- [ ] **Step 2: Check mock mode manually**
+
+Run:
+
+```bash
+VITE_API_MOCK=true npm run dev -w apps/frontend
+```
+
+Expected: frontend starts with browser MSW available and does not require the backend for the basic local flow.

docs/features/frontend-infrastructure-hardening/tasks.md

@@ -0,0 +1,34 @@
+# Frontend Infrastructure Hardening — tasks
+
+Статус: pending
+
+## 1. Включить browser mock mode
+
+- [ ] Добавить `apps/frontend/mocks/browser.ts` с `setupWorker`
+- [ ] Подключить worker в `apps/frontend/src/main.tsx` через `VITE_API_MOCK`
+- [ ] Обновить frontend docs, чтобы явно описать mock-free vs mock-enabled dev flow
+
+## 2. Валидация env
+
+- [ ] Описать обязательные `VITE_*` переменные в `apps/frontend/src/shared/config/env.ts`
+- [ ] Провалить старт приложения на невалидной конфигурации до рендера
+- [ ] Проверить, что сообщение об ошибке не раскрывает секреты
+
+## 3. Tooling consistency
+
+- [ ] Проверить `apps/frontend/package.json` и синхронизировать скрипты с текущим состоянием проекта
+- [ ] Обновить docs, где перечислены команды разработки, lint и build
+- [ ] Удалить или переписать устаревшие упоминания старых миграционных шагов
+
+## 4. Contract freshness
+
+- [ ] Привести frontend API docs к текущему source of truth
+- [ ] Проверить, что generated types остаются generated, а не редактируются вручную
+- [ ] Убедиться, что frontend shared API entrypoints не ссылаются на устаревшие слойные соглашения
+
+## 5. Финальная проверка
+
+- [ ] Запустить `npm run lint -w apps/frontend`
+- [ ] Запустить `npm run test -w apps/frontend`
+- [ ] Запустить `npm run build -w apps/frontend`
+- [ ] Проверить `VITE_API_MOCK=true npm run dev -w apps/frontend` на локальном старте без backend