# 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.