chore: sync the frontend template from ebea300 to af3d8e6

Carries 359 template commits, tag v0.2.0 plus one documentation commit: the
generator-built feature index with its app, bounded-context and feature
declarations, the src/platform kernel and scale tooling, the 2026-09-24 src
review fixes, and the 2026-09-25 maturity review round with its CHANGELOG
[보안]/[계약] rows. 691 of the 824 template paths are applied, 85 of them
merged with product changes; 127 are not carried.

Product identity is unchanged: name, version 0.1.0, routes, design and the
TechLog domain.

Three decisions worth naming. TechLog stays composed directly, as the last
two syncs recorded; its directory carries a NOT_INSTALLED marker that says so,
and every installed-* composer takes the template's projection with TechLog
added on top. The reference sample is no longer installed: the template now
installs a feature only through feature-module.ts and context-routes.ts,
which load the screens this product deleted, so its three operations, six
schemas and one topic leave the registries, recorded as registry change
evidence. And AppRouter mounts the platform and TechLog routes only; the
template's bounded-context route gateway waits for a generator-installed
feature.

Required fixes: readSubject on the BFF session owner (without it every HTTP
Studio session would close as integration-failed), zod through the facade in
nine TechLog files, noUnusedLocals, and public/config.json written out to
match the local profile. Derived baselines were recomputed after reproducing
both sides' values: CI contract 101 commands / 106 references / 141
artifacts, gate shape c9adcf85; registry approval 2dc6c3a3; the runtime
config schema baseline equals the schema at 8210d48.

Verified here: types, lint, architecture, adapter inventory, CI contract,
i18n, design system, diagnostics, browser security, dev release manifest,
TechLog contract and build pass; 220 component, 155 integration, 15
contract, 418 TechLog, 43 reference-feature, 18 recipe and 46
release-coherence tests pass, and 2381 of 2383 unit tests. Reproduced at
8210d48 first and unchanged: check:registries (byte-identical),
test:runtime-schema, verify:documentation. Brought by the template and
escalated rather than suppressed: check:request-fanout on TechLog's cursor
pagination, check:remediation-ledger (fails upstream too), the shared-chunk
hash test, and the registry-dependent sample removal and second-feature
tests. Playwright suites were not run.

Full record, the five open questions and the follow-ups in
docs/operations/template-sync-2026-09-29.md.

(cherry picked from commit b2170cf265dea45dc9cc05d3c61e627e97f31cdb)
This commit is contained in:
DongHyeonka
2026-11-12 08:28:54 +09:00
parent 585c62431a
commit c80320dfc7
738 changed files with 55027 additions and 13567 deletions
+180 -7
View File
@@ -25,8 +25,54 @@ corepack pnpm install --frozen-lockfile
corepack pnpm dev
```
Runtime-public settings live in `public/config.json` and are validated before
the product tree mounts. Client secrets are forbidden.
## Runtime configuration
Runtime-public settings are validated against one schema before the product
tree mounts (`runtimeConfigV2ArtifactSchema` in
`src/contracts/release-artifacts.ts`). Client secrets are forbidden.
The source of truth is `config/runtime/<profile>.json`, one file per
environment: `local`, `development`, `staging`, `production`. `corepack pnpm
build` writes `dist/config.json` from the selected profile
(`scripts/generate-runtime-config.ts`). `public/config.json` is only the local
profile for `corepack pnpm dev`; the build replaces it, so settings put there
never reach a deployment. Keep it equal to `config/runtime/local.json` plus
`BUILD_ID: local-build` and `RELEASE_ID: local-release`;
`tests/unit/deployment-admission.test.ts` fails when the two differ.
Build and deploy variables, lowest precedence first:
| Variable | Sets | Default |
| --- | --- | --- |
| `APP_PROFILE` | which `config/runtime/<profile>.json` is used | `local`; an empty value fails the build |
| `RUNTIME_API_BASE_URL` | `API_BASE_URL`, overriding the profile | the profile value |
| `RUNTIME_TELEMETRY_ENDPOINT` | `TELEMETRY_ENDPOINT`, overriding the profile | the profile value |
| `VITE_BUILD_ID` | `BUILD_ID` in the runtime config and the release manifest | `local-build` |
| `RELEASE_ID` | `RELEASE_ID` in the runtime config and the release manifest | `local-release` |
| `RELEASE_TARGET` | the environment FE-GATE-027 admits the build to; must equal `APP_PROFILE` | none; admission refuses without it |
`verify:documentation` fails if this table stops naming a variable the build or
admission reads (`scripts/verify-documentation-readiness.ts`).
Only the two `RUNTIME_*` values can differ from the reviewed profile. Anything
else changes by editing the profile file. Staging and production reject demo
auth and non-HTTPS endpoints.
A production build and its admission check:
```bash
APP_PROFILE=production \
RUNTIME_API_BASE_URL=https://api.example.com/ \
RUNTIME_TELEMETRY_ENDPOINT=https://telemetry.example.com/v1/events \
VITE_BUILD_ID=<unique build id> RELEASE_ID=<unique release id> \
corepack pnpm build
APP_PROFILE=production RELEASE_TARGET=production corepack pnpm check:release-admission
```
With `CI=true` the gate runner (`corepack pnpm ci:gate`) also requires
`VITE_COMMIT_SHA`, `SOURCE_DATE_EPOCH` and `CI_RUNNER_IMAGE` before it runs a
gate (`scripts/lib/build-environment.ts`, `scripts/run-ci-gate.ts`). The CI variable
list is in [`docs/operations/ci-quality-gates.md`](docs/operations/ci-quality-gates.md).
## TechLog experience
@@ -130,6 +176,46 @@ hand-written:
this sandbox. Run it any time to confirm the vendored contract has not
drifted from what was last generated.
## Support scope
Four tiers. The status words on the right are the ones the catalogs and
design documents use; the next table maps them.
| Tier | What it covers | Status words |
| --- | --- | --- |
| Default | In the default build and covered by the merge gates: the TechLog Public and Studio shells and routes, the REST HTTP executor, TanStack Query server state, Local/Session Storage registries, cross-tab invalidation, runtime config profiles and the release manifest check, `AUTH_MODE=external` (`demo` only in local/development), and the typed message catalog. `dist/` is served by a static host ([`docs/architecture/static-delivery.md`](docs/architecture/static-delivery.md)) | `COMPOSED` |
| Optional (recipe) | Not installed. A project copies one of the recipes in `config/recipes/frontend-capability-recipes.json` and narrows it ([`docs/architecture/optional-adapter-recipes.md`](docs/architecture/optional-adapter-recipes.md)). `realtime`, `offline-indexeddb`, `service-worker-pwa` and `file-transfer` also ship a tested reference runtime that the default build leaves out | `RECIPE_AVAILABLE`, `NOT_INSTALLED`, `AVAILABLE_NOT_COMPOSED` |
| Experimental | Designed and decided, but the runtime is missing or unfinished; finish it before building on it. GraphQL, gRPC-Web, Connect-Web and Protobuf adapters, Range resumable download, IndexedDB query persistence, the local preview decode-safety probe. `src/features/local-draft-feature` is an architecture sample, not installed; so is `src/features/reference-feature`, the template's removable sample, whose screens this product deleted | `DESIGNED_NOT_IMPLEMENTED` |
| Not supported | Deliberately not selected, or browsers cannot guarantee it: SSR, app-managed background upload and download, directory selection, persistent file handles, product query persistence, exactly-once delivery between tabs | `NOT_SELECTED`, `PLATFORM_LIMITED` |
The rows come from
[`docs/architecture/browser-data-capability-completion-ledger.md`](docs/architecture/browser-data-capability-completion-ledger.md),
[`docs/architecture/client-cache-and-storage.md`](docs/architecture/client-cache-and-storage.md)
and
[`docs/architecture/api-contract-schema-mapper-and-server-state.md`](docs/architecture/api-contract-schema-mapper-and-server-state.md).
| Status word | Where it appears | Meaning | Tier |
| --- | --- | --- | --- |
| `COMPOSED` | capability ledger, design documents | wired into the default production path | Default |
| `INSTALLED` | a project's own recipe catalog (step 10 of the recipe procedure) | the project added the recipe | Default, for that project |
| `RECIPE_AVAILABLE` | recipe catalog `status` | a recipe exists to copy; nothing is installed | Optional |
| `NOT_INSTALLED` | recipe catalog `defaultStatus`; a `src/features/<id>/NOT_INSTALLED` marker file | not part of the build | Optional (recipe) or Experimental (feature) |
| `AVAILABLE_NOT_COMPOSED` | capability ledger; recipe `referenceRuntime.status` | code and tests exist; the default build leaves it out | Optional |
| `DESIGNED_NOT_IMPLEMENTED` | capability ledger, design documents | design approved, runtime missing | Experimental |
| `NOT_SELECTED` | capability ledger, design documents | deliberately not chosen | Not supported |
| `PLATFORM_LIMITED` | capability ledger | browsers cannot guarantee it; offered only behind a probe and a fallback, if at all | Not supported as a guarantee |
Gate results (`PASS`, `PASS_SCOPED`, `UNVERIFIED`, `FAIL_UNVERIFIED`) are
verdicts on evidence, not support tiers.
Browsers: the build targets Chrome and Edge 111, Firefox 128, and Safari and
iOS 16.4. That is the higher of Vite 8's default JavaScript target
(`baseline-widely-available`; `vite.config.ts` sets no `build.target`) and
the CSS targets of Tailwind CSS 4. There is no browserslist. The end-to-end
suite runs on the desktop Chromium, Firefox and WebKit builds that Playwright
1.62 pins, plus one Chromium phone-size smoke (`playwright.config.ts`). Older
versions inside the target range and real mobile browsers are not tested.
## Architecture
This repository is a **Frontend Application Foundation**: a starter/composition
@@ -184,6 +270,31 @@ project-owned integrations. They are target designs and review findings; a
capability is not treated as implemented until its branch acceptance criteria
and executable gates pass.
## Documentation
[`docs/README.md`](docs/README.md) sorts the documents into current contracts,
target designs and work history.
### Files you can delete after copying
These record how the template and this product were built. Nothing in the
build or the gates reads them, except the one file noted below
(`tests/unit/deletable-history-documents.test.ts` checks this).
| Path | Contents |
| --- | --- |
| `docs/superpowers/` | past plans and specs |
| `docs/reviews/` | reviews. Keep `docs/reviews/adapters/INVENTORY.md`: `check:adapter-inventory` (FE-GATE-010) reads it |
The template's own `SPEC.md`, `tasks/` and `CLAUDE.md` were never carried
into this repository (`docs/operations/template-sync-2026-09-29.md`).
The reference feature is not in this list: deleting its directory alone
leaves tests, policy entries and CI scripts behind that fail the gates.
`scripts/test-sample-removal.ts` removes it from a copy of
the repository and lists everything that has to go with it (its header comment
and `SAMPLE_EXTRAS`); do the same in your project and run the gates.
## Verification
Common local checks:
@@ -212,6 +323,11 @@ corepack pnpm exec playwright test tests/e2e/tech-log-public-discovery.spec.ts t
corepack pnpm test:visual
```
`drill:runbooks` stops at the first drill that is not `PASS`. Without provider
evidence every drill ends `UNVERIFIED` (exit 3), because a drill never reports
a check it could not run locally as `PASS`; see "Runbook jobs" in
[`docs/operations/ci-quality-gates.md`](docs/operations/ci-quality-gates.md).
`test:all` is the ordinary product-development loop and intentionally excludes
host-level CI-runner assurance. Run `corepack pnpm test:system` only on the
compatible Linux assurance host described in
@@ -241,8 +357,8 @@ corepack pnpm exec playwright install --with-deps chromium firefox webkit
Two gates intentionally need external evidence:
- `review:a11y-manual` needs a signed human keyboard/focus/screen-reader review
for all 27 registered routes:
- `review:a11y-manual` (release gate FE-GATE-028) needs a signed human
keyboard/focus/screen-reader review for all 27 registered routes:
`NOT_FOUND`, `TECH_LOG_CASE`, `TECH_LOG_EXPLORE`, `TECH_LOG_EXPLORE_KIND`,
`TECH_LOG_HOME`, `TECH_LOG_PROFILE`, `TECH_LOG_PROJECT`,
`TECH_LOG_PROJECTS`, `TECH_LOG_PROJECT_ACTIVITY`,
@@ -255,15 +371,19 @@ Two gates intentionally need external evidence:
`TECH_LOG_STUDIO_NOT_FOUND`, `TECH_LOG_STUDIO_PUBLICATIONS`,
`TECH_LOG_STUDIO_PUBLICATION_PREVIEW`, `TECH_LOG_TOPIC`.
`verify:documentation` derives that list from the route registry and fails if
this paragraph falls behind it.
this paragraph falls behind it. The merge gate FE-GATE-009 runs only
`review:a11y-manual -- --format-only`, which checks that every route record
keeps the template's fields, reviewed or still pending.
- `collect:web-vitals-evidence` stays `FAIL_UNVERIFIED` until a reviewed minimum
eligible-sample threshold and 28 days of production data exist.
Live release verification additionally requires `HOSTING_BASE_URL`.
Live hosting verification (FE-GATE-019, production stage) requires
`HOSTING_BASE_URL` and a deployed promoted release; without it the result is
`UNVERIFIED`, not `PASS`.
## CI and evidence
The 27-gate registry is `config/ci/gates.json`; the Gitea workflow is
The gate registry is `config/ci/gates.json`; the Gitea workflow is
`.gitea/workflows/quality-gates.yml`. It follows:
```text
@@ -271,8 +391,61 @@ MERGE_READY -> RELEASE_READY -> PROD_PROMOTION_READY -> FIELD_SLO_READY
```
`DOCUMENTATION_READY` is independent. No gate is downgraded to a warning.
The workflow runs on pull requests, pushes to `main`, and `v*` tags. The Git host of this repository may not have Actions enabled, so a pull
request can show no gate status at all; no status is not a pass. Until the
host runs the workflow and marks the merge gates as required checks, run the 13
merge gates locally before merging (FE-GATE-008 and 009 need Playwright
browsers):
```bash
for gate in 001 002 003 004 005 006 007 008 009 010 011 013 020; do
corepack pnpm ci:gate -- "FE-GATE-$gate" || break
done
```
Machine-readable evidence is written below `artifacts/`; generated evidence is
ignored by Git while `.gitkeep` files preserve the taxonomy.
Operational details are in `docs/operations/`, with incident procedures in
`docs/runbooks/`.
## Updating a copied project
Template versions are Git tags `vX.Y.Z`. The template repository's
`CHANGELOG.md` lists the changes between tags, marks security fixes **[보안]** and contract changes
**[계약]** (backend, deployment, CI or feature code must change too), and names
the affected paths.
Record where you started. The template suggests a one-line `.template-origin`
file; this repository records the same thing, more precisely, in
`template.lock.json` (`sourceRevision` and `sourceTree`), and every sync is
written up in `docs/operations/template-sync-*.md`.
Take a template fix with Git. `cherry-pick` works even when your repository
does not share the template's history, because it merges against the picked
commit's parent:
```bash
git remote add template <template repository URL>
git fetch template --tags
git log --oneline <your origin>..template/main # what changed since you copied
git cherry-pick -x <commit> # one fix; -x records its origin
```
When the files have moved or diverged too far for a clean pick, read the
change as a diff and apply it by hand:
```bash
git diff <commit>^ <commit> -- <paths from CHANGELOG>
```
Afterwards run the local merge gates from "CI and evidence", apply the
backend or deployment change a **[계약]** row names, and update
`template.lock.json` once you have caught up to a tag. `git revert` undoes a pick.
Defects: if a problem reproduces on an unmodified checkout of the template at
`template.lock.json`'s `sourceRevision`, it is a template defect. Report it on the template
repository with that commit and the reproduction; the template maintainer
classifies it and ships the fix with a CHANGELOG entry. A problem that needs
your changes to reproduce belongs to your project, and applying a template fix
to your copy is your project's job.