diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 00000000..48f486b0 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,78 @@ +# 변경 이력 + +이 템플릿을 복사해 쓰는 프로젝트가 원본의 수정을 골라 가져갈 때 보는 문서다. +가져오는 방법은 `README.md`의 "Updating a copied project" 절에 있다. + +- 버전은 git 태그 `vX.Y.Z`로 식별한다. 태그 사이의 변경을 여기 적는다. +- **[보안]** 복사한 프로젝트도 가져가야 하는 보안·개인정보 수정이다. +- **[계약]** 백엔드, 배포 설정, CI, 또는 기능 코드가 함께 바뀌어야 하는 변경이다(헤더, 변수, 게이트, 공개 포트). +- 표시가 없으면 템플릿 안에서 끝나는 수정이다. +- 괄호 안 ID는 리뷰 발견 ID다. 근거와 재현 조건은 해당 리뷰 문서에 있다. +- 커밋 해시는 브랜치 `fix/maturity-review-2026-09-25` 기준이다. 병합 방식에 따라 `main`에서는 해시가 다를 수 있으니 ID로 찾는다(`git log --grep '03-03'`). + +## 0.2.0 — 진행 중 + +2026-09-25 성숙도 리뷰(`docs/reviews/2026-09-25-maturity-review/`) 수정 묶음이다. +기준은 `main` `4626b73`이다. 통합이 끝나면 태그 `v0.2.0`을 붙이고 이 절을 확정한다. +`package.json`의 `version`은 아직 `0.1.0`이다. + +### 보안·계약 변경 + +먼저 볼 항목이다. 복사한 프로젝트가 이 경로를 고쳤다면 충돌을 직접 풀어야 한다. + +| 표시 | 변경 | 영향 경로 | 커밋 | +|---|---|---|---| +| [계약] | 모든 V3 HTTP 요청이 논리 실행마다 `x-correlation-id` 헤더를 하나 보낸다. 다른 origin API는 preflight `Access-Control-Allow-Headers`에 이 헤더를 넣어야 요청이 나간다. 응답의 같은 헤더를 읽으려면 `Access-Control-Expose-Headers`에도 넣는다 (03-03) | `src/adapters/http/http-execution-v3.ts`, `src/adapters/http/feature-http-binding.ts`, `src/bootstrap/runtime-adapters.ts`, `docs/operations/api-contract-and-server-state-recovery.md` | `c5da3cf`, `f0a6495` | +| [계약] | 결과를 모르는 쓰기(응답 유실)를 다시 보낼 때 처음의 멱등 키를 그대로 쓴다. 백엔드는 같은 키의 재전송을 한 번만 적용해야 한다 (03-01, 08-03) | `src/presentation/adapters/query/application-query.ts`, `src/presentation/forms/use-app-form.ts`, `src/presentation/components/async-surface.tsx` | `dfb1b9e` | +| [계약] | 명령의 401/403/429를 기능 패키지가 분류할 수 있다(`classifyStatus`, 선택 필드). 재로그인이 먼저다 (03-02) | `src/adapters/http/http-effect-certainty.ts`, `src/adapters/http/http-execution-v3.ts`, `src/contracts/errors.ts`, `src/contracts/external-contract-runtime.ts` | `2afee67` | +| [계약] | 422 problem body의 필드 오류(`path`, `code`)를 폼까지 전달한다 (03-04) | `src/adapters/http/feature-http-binding.ts`, `src/features/reference-feature/contracts/reference-schemas.ts` | `479acd5` | +| [계약] | 텔레메트리 수집기 이벤트마다 `build_id`, `release_id`가 붙는다. 한 번에 보내는 본문은 60KiB 아래로 나뉜다 (13-11, 03-05) | `src/adapters/telemetry/telemetry-collector.ts`, `src/bootstrap/runtime-adapters.ts` | `43e47f4`, `e14c613` | +| [보안] | 번들이 읽지 않는 `VITE_*` 값까지 통째로 넣던 문제를 고쳤다. 값은 키로만 읽고, `ENV_REGISTRY`에 없는 `VITE_*` 이름은 빌드를 멈춘다 (13-06) | `src/contracts/env.ts`, `vite.config.ts`, `eslint.config.ts` | `2ec59ad` | +| [보안] | 로그아웃·계정 삭제 purge가 손상된 IndexedDB 때문에 열리지 않으면 그 파티션의 DB를 지운다. OPFS purge는 남은 chunk를 바로 지운다 (05-03, 05-04) | `src/adapters/platform/indexeddb-connection.ts`, `src/adapters/storage/indexeddb/indexeddb-runtime.ts`, `src/adapters/storage/opfs/opfs-byte-store-adapter.ts`, `src/application/ports/browser-file-storage/` | `3e37fbf`, `6ab564f` | +| [계약] | `RELEASE_TARGET`이 `APP_PROFILE`과 다르면 배포 승인이 거절된다 (12-02, 13-01) | `scripts/check-release-admission.ts`, `.gitea/workflows/quality-gates.yml` | `239b22a` | +| [계약] | 설정·매니페스트 URL이 `VITE_ROUTER_BASE_PATH`를 따른다. base 밖의 설정 URL은 빌드를 멈춘다 (13-07) | `scripts/generate-runtime-config.ts`, `src/contracts/env.ts`, `vite.config.ts` | `e215c84` | +| [계약] | `VITE_PRODUCT_FEATURES`는 생성기에서 적용되고, 모르는 기능 ID는 빌드를 멈춘다 (09-02) | `scripts/generate-product-feature-index.ts`, `src/contracts/product-features.ts` | `a8111f7` | +| [계약] | `src/features//`에 `feature-module.ts`도 `NOT_INSTALLED` 표식도 없으면 생성기가 실패한다. 기능 제거 검사는 `--feature=`를 받는다 (09-07, 14-03) | `scripts/generate-product-feature-index.ts`, `scripts/test-sample-removal.ts`, `config/contracts/registry-governance.json`, `docs/architecture/starter-experience.md` | `ad0e83c` | +| [계약] | 기능 루트·context·app 파일은 `src/adapters`를 import할 수 없다. presentation은 app·context를 import할 수 없다(`app-router.tsx` 예외) (12-03) | `scripts/check-architecture.ts`, `.dependency-cruiser.json`, `docs/architecture/layers.md` | `f8b6a36` | +| [계약] | CI 계약의 게이트 수·해시가 `config/ci/contract-baseline.json`으로 옮겨졌다. 게이트를 바꾸면 `update:ci-contract-baseline`로 갱신한다 (14-02) | `config/ci/contract-baseline.json`, `scripts/check-ci-contract.ts` | `0114b1e` | +| [계약] | 모든 테스트 파일은 어떤 게이트가 돌리거나 `config/ci/ungated-tests.json`에 이유가 있어야 한다 (12-04, 09-11, 11-03) | `config/ci/gates.json`, `config/ci/ungated-tests.json`, `scripts/lib/ungated-tests.ts` | `840de45`, `45ee231` | +| [계약] | 게이트 판정 변경: 서명된 수동 접근성 검토는 release 게이트 FE-GATE-028로, runbook drill은 관측하지 못한 단계를 `UNVERIFIED`(exit 3)로, FE-GATE-016은 폐지, FE-GATE-019는 배포 뒤 production 단계에서 돈다 (08-06, 11-01, 13-03, 13-05) | `config/ci/gates.json`, `.gitea/workflows/quality-gates.yml`, `scripts/drill-runbook.ts`, `docs/operations/ci-quality-gates.md` | `7298275`, `7f889a6`, `a263d8c` | +| [계약] | `engineStrict`, `saveExact`를 `pnpm-workspace.yaml`로 옮겼다. 지원하지 않는 Node에서 설치가 실패한다 (13-09) | `pnpm-workspace.yaml`, `.npmrc` | `a5dc851` | +| [계약] | 폼 저장 실패에 재로그인·권한 없음·나중에 재시도 상태가 따로 생겼다 (08-01) | `src/presentation/forms/form-contracts.ts`, `src/presentation/forms/use-app-form.ts`, `src/presentation/forms/form-components.tsx` | `9894a70` | +| [계약] | browser-transfer 포트: `upload()` 실패의 recovery 값이 다섯 개로 정리됐고, 완료된 업로드는 `resourceId`를 잃지 않는다. 시간 제한이 바이트 수에 비례한다 (01-01~01-11). file-transfer recipe를 쓰는 프로젝트만 해당 | `src/application/ports/browser-transfer/`, `src/adapters/browser-transfer/` | `648fe4e`, `7b2cefb`, `5a6665a`, `426b6b8` 외 | +| [계약] | IndexedDB·OPFS 포트: 미래 스키마는 `INCOMPATIBLE`, 빈 receipt는 없음으로 본다 (05-01~05-14). offline-indexeddb recipe를 쓰는 프로젝트만 해당 | `src/application/ports/browser-file-storage/`, `src/adapters/storage/` | `7f45afa`, `47cf040`, `8fc816e` 외 | + +### 그 밖의 수정 + +- 부트: 앱 모듈 평가 실패, 분류되지 않은 오류, 재시도 가능한 실패에 오류 화면을 보여 준다 (09-03, 09-04, 09-10). `src/bootstrap/`, `src/presentation/boundaries/boot-error-shell.tsx` +- 부트: `FEATURE_OVERRIDES`의 모르는 키를 진단으로 남긴다 (09-09). `src/bootstrap/runtime-adapters.ts`, `scripts/check-release-admission.ts` +- 빌드: `dist` 파일을 다른 사용자도 읽을 수 있게 한다 (13-02). `scripts/lib/dist-permissions.ts` +- 공급망: 번들에 들어간 패키지 목록과 각 증거의 범위를 남긴다. 승격된 릴리스를 나중에 다시 검증한다 (13-12, 13-04). `scripts/lib/vite-module-inventory.ts`, `scripts/verify-exact-promotion-bundle.ts` +- 아키텍처 검사: dependency-cruiser 실행을 멈추고 import graph 하나로 검사한다. 경계 예외를 좁히고, 위반 메시지에 이유와 갈 곳을 적는다 (12-05~12-11). `scripts/check-architecture.ts` +- 기능 조립: `needs` 검사, 기능 두 개 설치 시 타입 유지, local-draft 샘플 정리 (09-01, 09-05, 09-06, 09-08, 09-12, 00-02). `src/features/`, `src/bootstrap/runtime-adapters.ts` +- 테스트 보강: production CSP 아래 빌드 smoke, 멱등 키 재사용, IndexedDB fake, KEYED 재시도 (13-08, 01-04, 05-08, 10-03) +- 샘플 제거: `test:sample-removal`이 다시 통과한다. 플랫폼 테스트가 샘플 대신 테스트 전용 기능을 쓴다 (14-01, 14-08, 00-01, 10-01). `scripts/test-sample-removal.ts`, `scripts/lib/removal-fixture.ts` +- 문서: README에 런타임 프로필·배포 변수·우선순위를 적고 `verify:documentation`이 변수 목록을 검사한다 (13-15). 성능 예산, 공급망, 운영 runbook 문서를 코드에 맞췄다 (13-13, 13-14, 03-06, 03-08). + +### 진행 중 (아직 통합되지 않음) + +아래 레인은 별도 브랜치에서 작업 중이다. 통합되면 위 두 절로 옮긴다. + +- 레인 B — browser-files·Cache Storage (02-01~02-09) +- 레인 D — realtime (04-01~04-08) +- 레인 F — Service Worker·Web Push (06-01~06-10). 푸시 구독 해지와 SW 빌드 설정이 바뀐다 +- 레인 G — contracts 호환성 규칙과 FE-GATE-014 (07-02~07-07, 13-10) +- 레인 H — presentation 문구·접근성·라우트 (07-01, 08-02, 08-04, 08-05, 08-07~08-13, 11-02) +- 레인 J — 테스트 체계 (10-02, 10-04~10-07, 11-04~11-08) +- 레인 M — 이 변경 이력, 문서 색인(`docs/README.md`), README 지원 범위 표, `public/config.json` 동기화 검사 (14-04~14-06, 13-15 후속) +- 통합 뒤 — `noUnusedLocals`, 문서 수치 현행화 (12-12, 14-07) + +## 0.1.0 — `main` `4626b73` (2026-09-24) + +태그가 없는 `main`이고 `package.json` 버전은 `0.1.0`이다. 이 커밋보다 앞에서 복사한 프로젝트는 아래 보안 수정부터 확인한다. + +| 표시 | 변경 | 영향 경로 | 커밋 | +|---|---|---|---| +| [보안] | 자격증명 헤더 값은 제어 문자가 없는 ByteString만 받는다. 대소문자만 다른 헤더 이름은 거절한다 (R-3.4) | `src/adapters/http/http-contract-bridge.ts`, `src/adapters/auth/external-session-adapter.ts` | `5e62b7e` | +| [보안] | REST v2 COMMAND는 POST/PUT/PATCH/DELETE만 쓴다. GET으로 선언된 명령이 CSRF 보호 없이 나가던 문제다 (R-7.4) | `src/contracts/api-operations.ts` | `f26fd18` | +| [보안] | 텔레메트리 리댁션이 문자열 중간의 토큰, URL 비밀 파라미터, 이메일을 가린다 (R-9.3) | `src/platform/telemetry/redact-telemetry.ts` | `4e0745c` | diff --git a/README.md b/README.md index ba496cf9..51ce9e84 100644 --- a/README.md +++ b/README.md @@ -33,8 +33,8 @@ 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`; nothing checks that -yet. +`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: @@ -91,6 +91,46 @@ owner described in The client route policy is user experience only; server authorization remains authoritative. +## 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 application shell and example 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), the typed message catalog, and the removable reference feature. `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 | `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//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 @@ -144,6 +184,29 @@ 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 was built. Nothing in the build or the gates +reads them, except the one file noted below. + +| Path | Contents | +| --- | --- | +| `docs/superpowers/` | past plans and specs | +| `docs/reviews/` | reviews and the review guide. Keep `docs/reviews/adapters/INVENTORY.md`: `check:adapter-inventory` (FE-GATE-010) reads it | +| `SPEC.md`, `tasks/` | requirements and task list of the 2026-09-25 review fix round | +| `CLAUDE.md` | review instructions for the template repository itself; replace it with your own | + +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: @@ -247,3 +310,43 @@ 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`. [`CHANGELOG.md`](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. Right after copying, commit a one-line +`.template-origin` file at the root of your project with the template tag (or +commit) you copied and the date, for example `v0.2.0 2026-09-26`. + +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