From edf44a2253fe487ae3573a48dd1fadf32f37794d Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Sat, 26 Sep 2026 00:05:06 +0900 Subject: [PATCH 1/5] fix(config): keep public/config.json equal to the local profile (F-5, 13-15) public/config.json is the copy dev serves and nothing compared it with config/runtime/local.json. A unit test now requires it to equal what a local build writes, and sample removal drops the feature override from it too. Co-Authored-By: Claude Opus 5.5 --- README.md | 4 ++-- scripts/test-sample-removal.ts | 22 ++++++++++------------ tests/unit/deployment-admission.test.ts | 7 +++++++ 3 files changed, 19 insertions(+), 14 deletions(-) diff --git a/README.md b/README.md index ba496cf9..afa71002 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: diff --git a/scripts/test-sample-removal.ts b/scripts/test-sample-removal.ts index 8113f6c1..55d6c10d 100644 --- a/scripts/test-sample-removal.ts +++ b/scripts/test-sample-removal.ts @@ -244,18 +244,16 @@ try { // Runtime profiles are product configuration. Once the feature is physically // removed, its override key must disappear too or the built config still - // advertises a source capability that no longer exists. - for (const profile of [ - "local", - "development", - "staging", - "production", - ] as const) { - const profilePath = path.join( - fixtureRoot, - "config/runtime", - `${profile}.json`, - ); + // advertises a source capability that no longer exists. public/config.json + // is the local profile `dev` serves and has to stay equal to it (F-5). + for (const configPath of [ + "config/runtime/local.json", + "config/runtime/development.json", + "config/runtime/staging.json", + "config/runtime/production.json", + "public/config.json", + ]) { + const profilePath = path.join(fixtureRoot, configPath); const runtimeConfig = JSON.parse( await readFile(profilePath, "utf8"), ) as { diff --git a/tests/unit/deployment-admission.test.ts b/tests/unit/deployment-admission.test.ts index 2d3c57cb..4cff7b37 100644 --- a/tests/unit/deployment-admission.test.ts +++ b/tests/unit/deployment-admission.test.ts @@ -204,6 +204,13 @@ describe("runtime config profiles", () => { ).toBeGreaterThan(0); }); + // F-5 (13-15). `corepack pnpm dev` serves public/config.json while every + // build writes the local profile instead, so the two copies must not drift. + it("keeps public/config.json equal to what a local build writes", async () => { + const served: unknown = JSON.parse(await readFile("public/config.json", "utf8")); + expect(served).toEqual(await generateRuntimeConfig("local", {})); + }); + // 13-01: the build profile and the admission target are two repository // variables. A staging profile left in place for a production release has to // stop the release, whatever the built document happens to say. From 1cb09e42100b2ebc80aaea30866a27a2b183c2b0 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Sat, 26 Sep 2026 00:07:49 +0900 Subject: [PATCH 2/5] docs(template): add a CHANGELOG and the copied-project update procedure (14-04) A copy had no way to learn that a fix shipped or which files to take. The CHANGELOG marks security and contract changes with their paths; README says where to record the origin commit, how to cherry-pick or diff a fix and who classifies a template defect. The v0.2.0 tag is added after integration. Co-Authored-By: Claude Opus 5.5 --- CHANGELOG.md | 78 ++++++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 40 +++++++++++++++++++++++++++ 2 files changed, 118 insertions(+) create mode 100644 CHANGELOG.md diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 00000000..60591828 --- /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`에 병합된 첫 기준이다. 이보다 앞에서 복사한 프로젝트는 아래 보안 수정부터 확인한다. + +| 표시 | 변경 | 영향 경로 | 커밋 | +|---|---|---|---| +| [보안] | 자격증명 헤더 값은 제어 문자가 없는 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 afa71002..b54c70aa 100644 --- a/README.md +++ b/README.md @@ -247,3 +247,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