# STANDALONE-002 — Local Mocking Bird checkout console

## Status

Done

## Purpose

Keep the Mocking Bird console available in local development so an operator can manually settle
mocked checkout requests and exercise payment handling end to end. Preserve the environment
boundary: automated tests use the deterministic fake, local runs use Mocking Bird, and hosted
staging/production use the configured real provider.

## Scope

Register and render `/developer/mocking-bird` by default in the local Vite development server and
the local Docker Compose build. In staging and production builds, the console is never registered,
including when the developer-tools flag is accidentally set. The backend remains independently
authoritative: Mocking Bird endpoints and checkout are unavailable in hosted environments.

| Environment       | Checkout behavior                                                                                                                       |
| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| Automated tests   | `CHECKOUT_MODE=fake`, deterministic and network-free                                                                                    |
| Local development | `CHECKOUT_MODE=mocking-bird`, manually settled in the console                                                                           |
| Staging           | `CHECKOUT_MODE=surfboard` with the provider's test/Demo endpoint and credentials supplied only through deployment environment variables |
| Production        | `CHECKOUT_MODE=surfboard` with the provider's Live endpoint and credentials supplied only through deployment environment variables      |

No provider credentials or real payment calls are added to the repository.

## Acceptance scenarios

### STANDALONE-002-S01 — Local startup exposes the Mocking Bird console

- **Given** a developer starts the local Vite server or the local Docker Compose environment
- **When** an authenticated developer opens the application
- **Then** the Mocking Bird page is registered and visible in the navigation without an extra
  developer-tools opt-in
- **And** local checkout requests use Mocking Bird and can be manually settled through the console
- **Evidence:** frontend developer-tool, page-registry, and app-layout tests prove default local
  navigation visibility, including after a transient session refresh error; console tests prove
  manual checkout settlement; Docker configuration tests prove local setup. Include this scenario ID
  in executable test titles.

### STANDALONE-002-S02 — Hosted environments never render Mocking Bird

- **Given** a staging or production frontend build
- **When** it is built with its hosted deployment classification, even if the developer-tools flag
  is true
- **Then** the Mocking Bird page and navigation entry are absent
- **And** backend startup rejects Mocking Bird tooling or checkout configuration in hosted mode
- **Evidence:** frontend registry/flag tests cover staging and production; backend configuration
  tests prove hosted Mocking Bird configuration is rejected. Include this scenario ID in executable
  test titles.

### STANDALONE-002-S03 — Checkout adapter follows the environment

- **Given** an automated test, local development, staging, or production
- **When** its checkout configuration is composed
- **Then** automated tests use the deterministic fake, local development uses Mocking Bird, and
  staging/production select the real Surfboard integration
- **And** staging test credentials and production Live credentials come from environment
  configuration outside this repository
- **Evidence:** backend configuration tests cover the allowed/forbidden adapter modes and hosted
  Surfboard setup; Docker validation configuration proves automated tests stay fake-backed while
  local Compose defaults to Mocking Bird. Include this scenario ID in executable test titles.

## Exclusions

No change to the checkout contract, provider adapter, credentials, or payment behavior. No Mocking
Bird page or endpoint is available in staging or production. This requirement does not add a hosted
test payment flow, nor does it change the deterministic gateway used by automated tests.

## Required validation

Run the frontend and backend tests, `pnpm test`, `pnpm test:coverage`, `pnpm build`, `pnpm quality`,
`pnpm docs:build`, `pnpm docs:site:check`, and `pnpm validate:docker`. Update the scenario evidence
index and implementation record with the exact tests and results.

## Implementation record

- **Status:** Done
- **Implementation tasks:** One focused frontend/build-configuration change; no separate task record
  was needed.
- **Scenario evidence:**
  - STANDALONE-002-S01: `frontend/src/app/pages.test.tsx`,
    `frontend/src/app/layout/AppLayout.test.tsx`,
    `frontend/src/pages/MockingBirdConsolePage.test.tsx`, and `tests/ci/docker-validation.test.mjs`.
  - STANDALONE-002-S02: `frontend/src/app/pages.test.tsx` and `backend/src/config.test.ts`.
  - STANDALONE-002-S03: `tests/ci/docker-validation.test.mjs` and `backend/src/config.test.ts`.
- **Validation:** `pnpm build`, `pnpm test` (56 CI, 307 frontend, 496 backend unit tests),
  `pnpm test:coverage` (307 frontend and 588 backend tests; 100% statements, branches, functions,
  and lines), `pnpm quality`, `pnpm docs:build`, `pnpm docs:site:check`, and `pnpm validate:docker`
  passed. Docker validation passed with 92 PostgreSQL integration tests, backend restart/durability
  verification, and 82 desktop/mobile browser tests. `pnpm test:coverage` used the local PostgreSQL
  service for the dedicated integration-test databases. The follow-up session-refresh regression
  initially failed before the AppLayout fix, then passed; `pnpm test` passed with 308 frontend tests
  and `pnpm quality` passed.
- **Notes:** Vite development automatically enables the console. Static builds require both
  `VITE_DEPLOYMENT_ENV=local` and `VITE_ENABLE_DEVELOPER_TOOLS=true`; local Compose supplies these
  by default. The application shell retains navigation for a cached authenticated user during a
  transient non-401 session refresh error; protected routes remain guarded. Hosted and unclassified
  builds remain excluded.