문제
리뷰 16-08이 적은 다섯 문장 중 넷이 f887817에서도 코드와 다르다.
- 01 3단계: 라우트 루트 검사를 tests/architecture/context-route-roots.test.ts가
"실행한다"고 적는다. 그 테스트는 fixture만 쓰고 설치된 기능을 보지 않는다.
실제로 막는 것은 앱 모듈을 적재하는 테스트와 부팅이다.
- 01 3단계·02 결정표: 인증 프로필이 틀리면 "operation을 적재하는 모든 게이트가
실패한다". 변이로 확인하면 check:registries와 그 기능을 적재하는 테스트만
실패하고 check:types·check:architecture·verify:documentation은 통과한다.
- 01 8단계: "서버 422 오류를 받을 필드". 짝 백엔드의 필드 검증은 400
VALIDATION_FAILED + details다. 공유 MSW 시나리오의 validation-422는
Envelope operation에서 결과 불명이다.
- starter-experience.md: "`NoRequest` already belongs to the sample". src에
NoRequest가 없다. 생성 명령이 <Pascal>NoRequest를 쓴다.
다섯째("테스트 2개")는 생성기 브랜치가 이미 고쳤다(테스트 3개와 test-app).
고른 방법
문장만 고친다. 리뷰가 검토하라고 한 공유 시나리오 validation-400 추가는 하지
않았다. 문서 작업 범위 밖이고, 생성된 작성 폼 테스트가 400 본문을 이미 손으로
적는다. 매뉴얼에 그 테스트를 가리켰다.
위험·한계
- 문장의 게이트 목록은 참조 기능에 넣은 변이 한 번으로 확인했다. build는
돌리지 않았다.
검증
- 인증 프로필 오타 변이: check:registries rc=1(reason 포함), check:types rc=0,
check:architecture PASS, verify:documentation PASS_SCOPED. 되돌림.
- verify:documentation PASS_SCOPED, documentation-readiness 테스트 통과.
Refs: docs/reviews/2026-11-03-maturity-review/16-structure-patterns.md 16-08
295 lines
19 KiB
Markdown
295 lines
19 KiB
Markdown
# Starter experience contract
|
|
|
|
The repository provides a runnable, domain-neutral application rather than
|
|
only infrastructure contracts. The starter experience is intentionally
|
|
replaceable at the page level while the shell, providers, boundaries,
|
|
primitives, and state surfaces remain reusable.
|
|
|
|
## Runtime composition
|
|
|
|
```text
|
|
validated config + coherent release manifest
|
|
-> concrete adapters
|
|
-> QueryClientProvider
|
|
-> ApplicationProvider
|
|
-> RouterProvider
|
|
-> ThemeProvider
|
|
-> SessionProvider
|
|
-> AppShell
|
|
-> lazy route boundary
|
|
```
|
|
|
|
Boot stops before product mount when configuration or release coherence fails.
|
|
Each lazy page renders inside Suspense and a telemetry-aware route boundary.
|
|
Route changes move focus to the new page heading; the skip link and landmarks
|
|
remain stable in the shell.
|
|
|
|
## Registered routes
|
|
|
|
The route list is `ROUTE_REGISTRY` (`src/features/installed-feature-contracts.ts`):
|
|
the platform routes of `src/contracts/routes.ts` plus the routes of every
|
|
installed feature. The platform overview page (`/examples/platform`) shows the
|
|
composed list at runtime, so this document does not keep a copy of it.
|
|
|
|
Navigation labels and order come from `ROUTE_REGISTRY`; the sidebar does not
|
|
maintain a second route list. The client access decision never claims to be
|
|
authorization.
|
|
|
|
## Authentication seam
|
|
|
|
The session port exposes state subscription, sign-in start, sign-out,
|
|
credential attachment, recovery, and unauthenticated notification. Credentials
|
|
remain opaque to the application and presentation layers.
|
|
|
|
- `demo`: local/development-only state transition with no credentials
|
|
- `external`: delegates to `globalThis.__CA_FRONTEND_AUTH_OWNER__`
|
|
- missing/invalid external owner: fails closed as `integration-failed`
|
|
|
|
An external owner implements `readState`, `readSubject`, `subscribe`,
|
|
`beginSignIn`, `signOut`, `attachCredential`, `recoverSession`, and
|
|
`notifyUnauthenticated`. It owns token acquisition and storage. An owner that
|
|
lacks any of these methods is rejected, and the session fails closed as
|
|
`integration-failed`.
|
|
|
|
The state transitions an owner makes, and what `recover()` leaves behind for
|
|
each answer, are written on `SessionState` and `SessionGateway.recover` in
|
|
`src/application/ports/auth-session-port.ts`. For the paired backend's two
|
|
authentication modes there are owners to copy, not to write:
|
|
`recipes/session-owners/oidc-pkce-session-owner.ts` (JWT mode: Keycloak,
|
|
authorization code with PKCE, `EXTERNAL_BEARER`) and
|
|
`recipes/session-owners/cookie-session-owner.ts` (Redis session mode: the
|
|
session cookie, plus `SESSION_COOKIE_*` profiles and the `X-XSRF-TOKEN`
|
|
provider). `docs/manual/04-paired-backend-session.md` wires them and lists
|
|
what the backend template does not ship (a browser client in its realm; the
|
|
sign-in, sign-out and session endpoints).
|
|
|
|
`readSubject()` is required. The server-state cache is cleared only when the
|
|
session state or the subject changes, so a token refresh for the same user
|
|
keeps cached data. `readSubject()` must return:
|
|
|
|
- an opaque, non-empty string that stays the same for one user across token
|
|
refreshes and differs between users: the OIDC `sub` claim, Supabase
|
|
`session.user.id`, or Firebase `user.uid`
|
|
- `null` when nobody is signed in
|
|
- never an access token, refresh token, or any other credential
|
|
|
|
If `readSubject()` returns `null` or `""` while the owner reports
|
|
`authenticated`, the runtime cannot tell a refresh from an account switch. It
|
|
fails closed: every such notification clears server state, and each one records
|
|
the `cache.operation.failed` diagnostic with `operation: SCOPE_FENCE` and
|
|
`reason: SUBJECT_MISSING`. Seeing that diagnostic means the owner is not
|
|
reporting its subject. The `demo` adapter reports one fixed demo user as its
|
|
subject.
|
|
|
|
Migration: `readSubject()` used to be optional. An owner written for an earlier
|
|
release must add it; without it the owner is rejected at startup (the session
|
|
becomes `integration-failed`) and a TypeScript owner no longer compiles
|
|
against `ExternalSessionOwner`. A code path that implements `AuthSessionPort`
|
|
or `SessionGateway` directly must add `getSubject()` the same way.
|
|
|
|
## Extending the starter
|
|
|
|
New platform work should follow
|
|
[routing, page templates, and reusable patterns](./routing-pages-and-patterns.md)
|
|
and the
|
|
[TypeScript, state, and data-flow target](./typescript-state-and-data-flow.md)
|
|
rather than adding another independent route or data-loading convention.
|
|
|
|
### Replacing the starter screens
|
|
|
|
`/` (`src/presentation/pages/home-page.tsx`) is the platform's `APP_HOME`; a
|
|
feature takes it over by declaring that route id (see "Product home and
|
|
layouts"). Its starter links are the first three screens of the navigation.
|
|
|
|
The example screens `/examples/ui`, `/examples/states` and `/examples/auth`
|
|
are one feature, `src/features/platform-examples-feature/`, in its own context
|
|
`src/contexts/platform-examples-context/` (1103/09-04). A product turns them
|
|
off like any feature: leave the id out of `VITE_PRODUCT_FEATURES`, or remove
|
|
it with `corepack pnpm test:sample-removal -- --feature=platform-examples-feature`
|
|
as the drill. Their routes then leave the registry, the navigation, the
|
|
bundle and the manual accessibility list (FE-GATE-028). Their component tests
|
|
are in `tests/features/platform-examples-feature/` and go with them.
|
|
|
|
The platform overview (`/examples/platform`,
|
|
`src/presentation/examples/platform-overview-page.tsx`) stays a platform
|
|
route. It describes the installed registries, and the lab gate (FE-GATE-026)
|
|
times entering it: a feature route's first entry also loads its context's
|
|
routes module before the page, a second request round the 200 ms budget does
|
|
not fit. Its tests are the `tests/component/starter-*.test.tsx` files.
|
|
|
|
The platform's component tests (router, boundaries, shell, runtime tree) run
|
|
on the pages of the test-only feature in `tests/helpers/fixture-feature.tsx`
|
|
and keep passing without the examples. The browser-level checks in
|
|
`tests/e2e` and `tests/visual` use the example screens as their pages and run
|
|
where the examples are installed: a product that leaves them out points those
|
|
specs at its own screens or deletes them.
|
|
|
|
### Ownership declarations
|
|
|
|
Features, contexts and apps are discovered by
|
|
`scripts/generate-product-feature-index.ts`. Each boundary declares only its
|
|
parent, as exported string or integer literals the generator reads:
|
|
|
|
| File | Exports |
|
|
| --- | --- |
|
|
| `src/apps/<app>/app-module.ts` | `APP_MODULE_ID`, `APP_MAX_CONTEXTS` |
|
|
| `src/contexts/<context>/context-module.ts` | `CONTEXT_MODULE_ID`, `CONTEXT_APP_ID`, `CONTEXT_ROUTE_PATH`, `CONTEXT_MAX_FEATURES` |
|
|
| `src/features/<feature>/feature-module.ts` | `FEATURE_MODULE_ID`, `FEATURE_CONTEXT_ID`, `FEATURE_MODULE` |
|
|
| `src/features/<feature>/feature-runtime.ts` | `FEATURE_RUNTIME` (imported only by `feature-module.ts`, dynamically) |
|
|
| `src/features/<feature>/context-routes.ts` | `FEATURE_CONTEXT_ROUTES` |
|
|
| `src/contexts/<context>/context-layout.tsx` (optional) | `CONTEXT_LAYOUT`, the context's own layout ("Product home and layouts") |
|
|
|
|
The generator writes `src/.generated/` (git-ignored): the feature index the
|
|
installed catalogs import, the context index the router loads lazily, and the
|
|
selected app. Every build and check script runs it first; run it yourself with
|
|
`corepack pnpm generate:feature-index`. It fails, naming the file, when:
|
|
|
|
- a directory under `src/features/` has no `feature-module.ts` and no
|
|
`NOT_A_FEATURE` marker file (`src/features/local-draft-feature/NOT_A_FEATURE`
|
|
is the one intentional example), or has both;
|
|
- a feature names an undeclared context, or a context an undeclared app;
|
|
- a context or app exceeds its declared budget;
|
|
- `VITE_PRODUCT_FEATURES` names a feature the app does not declare. The
|
|
variable narrows the installed set here, before anything is compiled.
|
|
|
|
### Adding a feature
|
|
|
|
1. Create `src/features/<feature>/feature-module.ts`. Build `FEATURE_MODULE`
|
|
with `defineFeatureModule` (`src/features/feature-module.ts`). This is the
|
|
feature's declaration, and it is in the initial chunk, so it holds data
|
|
only: the declaration contract (routes, route runtime contracts,
|
|
invalidation, topic versions and the external `contractPackages` the
|
|
release manifest is checked against at boot), its message catalogs, and
|
|
`loadRuntime`, which imports `feature-runtime.ts` dynamically.
|
|
The reference sample's feature-module.ts (src/features/reference-feature,
|
|
while it is installed) is the complete example.
|
|
2. Create `src/features/<feature>/feature-runtime.ts` with
|
|
`defineFeatureRuntime`: the `schemas` (FE-REG-SCHEMA rows for the
|
|
feature's route and API schemas), the adapter contributions
|
|
(`defineFeatureAdapterContribution`, with `needs` naming the platform
|
|
capabilities it receives) and the contract contributions (the HTTP
|
|
operations). The router loads
|
|
it (`application.features.load`) when one of the feature's routes is
|
|
entered. Do not import it statically from anywhere: each feature would add
|
|
its whole executable code to the initial chunk again, about 3.9 KB gzip
|
|
(tests/unit/feature-shape-growth.test.ts, which goes with the reference
|
|
sample, bounds one feature at 1 KiB).
|
|
An HTTP API is written once, as its contract contribution descriptor: it
|
|
executes, and `check:registries` governs the FE-REG-API row projected from
|
|
it (`projectApiOperationRows` in `src/contracts/api-operations.ts`).
|
|
A product feature's contract contribution uses an `EXTERNAL_PACKAGE`
|
|
source. `TEMPLATE_FIXTURE` belongs to `reference-feature` only and never
|
|
joins the release contract set; the composer rejects it anywhere else.
|
|
3. Create `src/features/<feature>/context-routes.ts` exporting
|
|
`FEATURE_CONTEXT_ROUTES`. Page components are imported lazily here, and each
|
|
route handle carries the route's params/search `codecs`; the owning context
|
|
loads this file only when its route root is visited
|
|
(the reference sample's context-routes.ts shows one). Each handle's
|
|
`routeId` must be a route of a feature contract in the same context; the
|
|
context refuses the routes when they load, naming the route, context and
|
|
features (`src/contexts/bounded-context-module.ts`).
|
|
4. Name the owning context in `FEATURE_CONTEXT_ID`. Use an existing context or
|
|
add `src/contexts/<context>/context-module.ts` owned by the app.
|
|
Every route path in the feature contract must sit at or under that
|
|
context's `CONTEXT_ROUTE_PATH` and must not fall under another context's
|
|
identical or more specific root: the router renders feature routes only
|
|
inside the owning context. No platform route may answer it either: the
|
|
router tries `AppShell`'s platform routes first, so the same path as a
|
|
platform route, `/` under an id other than `APP_HOME`, or a `*` root
|
|
without a layout (the not-found route takes every URL) never renders the
|
|
feature. The app module refuses anything else when it loads, naming the
|
|
route, feature and context (`src/apps/deployable-app-module.ts`). A route
|
|
that takes over the platform home is the exception ("Product home and
|
|
layouts").
|
|
5. If the feature has application input, augment `ApplicationFeatureInputs`
|
|
from the feature (`src/features/local-draft-feature/application/local-draft-api.ts`).
|
|
6. Run `corepack pnpm check:architecture`, `corepack pnpm check:types`,
|
|
`corepack pnpm check:registries` and the tests. `tests/unit/two-feature-install-typecheck.test.ts`
|
|
keeps the installed catalogs compiling with more than one feature.
|
|
7. Run `corepack pnpm test:sample-removal -- --feature=<feature id>` to prove
|
|
the product still builds and passes its gates without the feature.
|
|
|
|
Files outside the feature directory. Everything else a feature needs is in
|
|
`src/features/<feature>/` and `tests/features/<feature>/`.
|
|
|
|
| File | When | What fails without it |
|
|
| --- | --- | --- |
|
|
| `src/.generated/*` | never by hand: every build and check script regenerates it | — |
|
|
| `src/contexts/<context>/context-module.ts` | the feature needs a new context | `generate:feature-index`: `Feature <id> belongs to undeclared context <context>` |
|
|
| `src/contexts/<context>/context-layout.tsx` | the context needs its own frame instead of `AppShell` (see "Product home and layouts" below) | nothing: without it the context renders in `AppShell` |
|
|
| `artifacts/tests/a11y-manual/<ROUTE_ID>.md` | every route the feature adds. Copy a record and reset it to `Status: pending-manual-review` | `test:unit` (`tests/unit/manual-a11y-evidence.test.ts`), `verify:documentation` (names the route IDs) and FE-GATE-009 (`review:a11y-manual -- --format-only`). FE-GATE-028 requires the signed review at release |
|
|
| `tests/e2e/accessibility.spec.ts` | never per feature (1103/16-03): it fills every path parameter with one value and answers each API request from the installed descriptor, a list read with an empty list in its `responseEnvelope` frame. Edit it only for a protected page that sends something other than an installed GET before it renders | `test:a11y` (FE-GATE-009): a request no installed GET declares fails the route; so does an alert box (`role="alert"`) on a page that read only lists |
|
|
| `src/features/product-capabilities.ts` (product-owned) | `needs` names a capability the template does not build: type it in `ProductFeaturePlatformCapabilities`. `FeaturePlatformCapabilities` extends it, so the app, scripts and tests typecheck programs all see the key (an augmentation inside `product-composition.ts` is not seen by the scripts' program) | `check:types`: `Type '"<capability>"' is not assignable to type 'keyof FeaturePlatformCapabilities'` in the feature |
|
|
| `src/bootstrap/product-composition.ts` (product-owned) | `needs` names a capability the template does not build: return the capability here, typed in `product-capabilities.ts`. `indexedDb` is built as in `recipes/frontend-capabilities/indexeddb-feature-capability.ts`. Credentials for a product auth profile are returned here too. A product that owns the session (a BFF's httpOnly cookie) returns its session owner from `composeProductSessionOwner` instead of installing it on the host global before boot | `check:types`; at runtime `feature <id> needs <capability>, which the host did not provide`. Without the session owner, `AUTH_MODE: "external"` boots with the session `integration-failed` |
|
|
| `src/contracts/product-contracts.ts` (product-owned) | a product auth profile, or a product runtime-config key and its FE-REG-ENV row (`PRODUCT_ENV_REGISTRY`) | auth profile: every gate that loads the operation, with `Installed contract contribution is not composable: <featureId>/<operationId>: unknown authProfileId <id>`. Config key: `check:types` where it is read. Give the key a `.default()` or make it `.optional()`: template tests build their config with `tests/helpers/runtime-config.ts`, which fills the product's defaults, and a required key without a default fails them. FE-REG-ENV row: `check:registries` checks its fields, and `tests/unit/env-registry-coverage.test.ts` (`test:unit`) requires a row for every key, with the schema's `required` and `defaultValue` |
|
|
| `config/runtime/<profile>.json` | optional: a `FEATURE_OVERRIDES` entry switches the feature off | nothing |
|
|
| `package.json`, the lockfile, `config/security/dependency-change-evidence.json` | the contract contribution imports a generated `@org-contracts/*` package as a production dependency | `generate:supply-chain` (in `check:bundle`): `high-risk dependency missing review: add:<package>` |
|
|
|
|
The central catalogs (`src/features/installed-*.ts`) and the registry
|
|
governance file do not change: consumer directories there are globs over every
|
|
feature (`src/features/*/adapters`, `config/contracts/registry-governance.json`).
|
|
A route's params/search schema ids are checked against the schemas the feature
|
|
registers, and its `loadingSurface` only has to be a kebab-case name, so a
|
|
route with its own schema and loading surface needs no governance edit either.
|
|
The registry baseline does not change either. New routes, API operations,
|
|
schemas and invalidation topics, namespaces and edges are additive registry
|
|
changes; `update:registry-baseline` or breaking evidence is needed only to
|
|
remove or change a row or graph item.
|
|
`tests/unit/second-api-feature-registries.test.ts` adds such a feature (an API
|
|
operation, a route with its own search schema and loading surface, and an
|
|
invalidation topic) to a copy of the repository and runs `check:registries` on
|
|
it.
|
|
|
|
Schema, operation, mapper, route and chunk ids and invalidation topics are
|
|
global. Prefix them with the feature; `create:feature` writes
|
|
`<Pascal>NoRequest`, so a bare `NoRequest` would collide between features. MSW scenarios for the feature's own operations come from
|
|
`createHttpScenarioHandler` (`tests/mocks/handlers/http-scenarios.ts`) with
|
|
the feature's installed contract; the shared scenario catalog does not change.
|
|
|
|
### Product home and layouts
|
|
|
|
A product whose home is a feature screen, or whose screens use a frame other
|
|
than `AppShell`, declares it. The router and the catalogs do not change.
|
|
|
|
- **Home.** A feature takes over the platform home by declaring a route with
|
|
the id `APP_HOME` in its contract. The platform names the routes a feature
|
|
may take over (`FEATURE_REPLACEABLE_PLATFORM_ROUTE_IDS` in
|
|
`src/contracts/routes.ts`); any other platform route id is still a
|
|
duplicate. Two features declaring `APP_HOME` fail when the catalogs load,
|
|
naming both. The router mounts the route at its own path with the owning
|
|
context, whatever that context's route root. Leaving the feature out of the
|
|
build (`VITE_PRODUCT_FEATURES`) brings the platform home back; switching it
|
|
off at runtime shows the disabled-feature page at its path.
|
|
- **Layout.** A context with `src/contexts/<context>/context-layout.tsx`
|
|
exporting `CONTEXT_LAYOUT` (a component) renders under that layout instead
|
|
of `AppShell`. The generated index loads the file lazily, when one of the
|
|
context's routes is entered. The router mounts the context at each
|
|
registered path of its features under the layout, so an unknown URL still
|
|
gets the not-found page in `AppShell`. Contexts whose layout files export the
|
|
same component keep one layout instance when the user moves between them,
|
|
so several route roots can share a layout.
|
|
- **Accessibility.** The layout renders a skip link to `#main-content` and
|
|
exactly one `<main id="main-content" tabIndex={-1}>` around `<Outlet />`.
|
|
The router moves focus there on every route change. Layout routes are
|
|
siblings of `AppShell`, never inside it.
|
|
`tests/component/layout-landmarks.test.tsx` renders `AppShell` and the
|
|
layout of every installed context and fails one without them.
|
|
- **Failures.** A layout chunk a deploy removed gets the reload-once recovery
|
|
of a route chunk. Route and feature boundaries work as they do in
|
|
`AppShell`.
|
|
- The route root rule of step 4 spans every layout: a root takes the URLs
|
|
under it whichever layout either context has.
|
|
|
|
`tests/component/context-layouts.test.tsx` installs a product declared this
|
|
way (`tests/helpers/fixture-layout-product.tsx`).
|
|
|
|
### Before shipping
|
|
|
|
- Use the semantic tokens, UI primitives, and state surfaces before adding a
|
|
project-specific variant.
|
|
- Add component behavior, all-engine E2E, automated axe, and signed manual
|
|
route evidence.
|
|
|
|
Theme preference is the public `COLOR_SCHEME` storage contract. Authentication
|
|
tokens and other secrets remain forbidden storage keys.
|