diff --git a/.claude/skills/fe-a11y/SKILL.md b/.claude/skills/fe-a11y/SKILL.md index d3b2def6..5d764f24 100644 --- a/.claude/skills/fe-a11y/SKILL.md +++ b/.claude/skills/fe-a11y/SKILL.md @@ -51,7 +51,7 @@ paths: 폼 -- [ ] label·설명·오류가 같은 ID 체계와 `aria-describedby`로 연결된다(M5). required는 기호와 programmatic 상태를 함께 가진다. 제출 실패 시 오류 요약으로 포커스가 간다. — DS 8.3절 +- [ ] label·설명·오류가 같은 ID 체계와 `aria-describedby`로 연결된다(M5). required는 기호와 programmatic 상태를 함께 가진다. 입력 오류로 제출이 실패하면 첫 오류 필드로 포커스가 가고, 오류 요약은 그 필드들로 가는 링크다(`src/presentation/forms/use-app-form.ts` `focusFirstError`). 입력 오류가 아닌 실패는 feedback 자리가 포커스를 받는다. — DS 8.3절 - [ ] IME 조합 중에 검증하거나 제출하지 않는다. — DS 8.1절 시각 diff --git a/.claude/skills/fe-ux/SKILL.md b/.claude/skills/fe-ux/SKILL.md index 3cb18f56..afa7fc08 100644 --- a/.claude/skills/fe-ux/SKILL.md +++ b/.claude/skills/fe-ux/SKILL.md @@ -58,7 +58,7 @@ paths: 폼 -- [ ] label·설명·오류가 연결되고, 제출 실패 시 오류 요약으로 포커스가 가며, 요약 항목은 그 필드로 간다. — `docs/design/2026-07-26-design-system-platform-design.md` 8.3절 +- [ ] label·설명·오류가 연결되고, 입력 오류로 제출이 실패하면 첫 오류 필드로 포커스가 가며, 오류 요약 항목은 그 필드로 간다(`src/presentation/forms/use-app-form.ts` `focusFirstError`). — `docs/design/2026-07-26-design-system-platform-design.md` 8.3절 - [ ] 409를 검증 오류로 위장하지 않는다. 이탈 확인(`useDirtyNavigationGuard`)은 성공 저장 뒤 풀고 이동한다. — `docs/design/2026-07-26-typescript-state-and-data-flow-design.md` 8절, `docs/design/2026-07-26-routing-pages-and-patterns-design.md` 6.4절 - [ ] 자동 완성·IME·붙여넣기·비밀번호 관리자를 막지 않는다. 입력을 loading skeleton으로 덮지 않는다. — data-flow 8절 diff --git a/.gitea/workflows/quality-gates.yml b/.gitea/workflows/quality-gates.yml index 44f3c4d3..4898c239 100644 --- a/.gitea/workflows/quality-gates.yml +++ b/.gitea/workflows/quality-gates.yml @@ -41,10 +41,34 @@ jobs: if: ${{ gitea.event_name != 'workflow_dispatch' || (inputs.stage != 'documentation' && inputs.stage != 'main') }} runs-on: ubuntu-latest timeout-minutes: 45 + env: + COREPACK_HOME: /tmp/fe-dependency-cache/corepack + PNPM_CONFIG_STORE_DIR: /tmp/fe-dependency-cache/pnpm-store + PNPM_CONFIG_CACHE_DIR: /tmp/fe-dependency-cache/pnpm-cache steps: - uses: https://github.com/actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 with: persist-credentials: false + - name: Restore and save the dependency cache + if: ${{ gitea.ref == 'refs/heads/main' }} + uses: https://github.com/actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 + with: + path: | + /opt/hostedtoolcache/node + /tmp/fe-dependency-cache + key: fe-dependencies-${{ runner.os }}-${{ runner.arch }}-${{ hashFiles('.nvmrc', 'pnpm-lock.yaml') }} + restore-keys: | + fe-dependencies-${{ runner.os }}-${{ runner.arch }}- + - name: Restore the dependency cache + if: ${{ gitea.ref != 'refs/heads/main' }} + uses: https://github.com/actions/cache/restore@0057852bfaa89a56745cba8c7296529d2fc39830 + with: + path: | + /opt/hostedtoolcache/node + /tmp/fe-dependency-cache + key: fe-dependencies-${{ runner.os }}-${{ runner.arch }}-${{ hashFiles('.nvmrc', 'pnpm-lock.yaml') }} + restore-keys: | + fe-dependencies-${{ runner.os }}-${{ runner.arch }}- - uses: https://github.com/actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 with: node-version-file: .nvmrc @@ -85,10 +109,34 @@ jobs: # FE-GATE-013 runner requirement: unprivileged user and network namespaces for bwrap (the provider sandbox runs bwrap --unshare-pid --unshare-ipc --unshare-uts --unshare-net); Ubuntu 23.10 and later refuse them while kernel.apparmor_restrict_unprivileged_userns=1 unless /usr/bin/bwrap has an AppArmor profile that allows userns; scripts/check-system-test-prerequisites.ts probes this before test:system runs and scripts/run-and-validate-provider.ts before a provider runs runs-on: ubuntu-latest timeout-minutes: 45 + env: + COREPACK_HOME: /tmp/fe-dependency-cache/corepack + PNPM_CONFIG_STORE_DIR: /tmp/fe-dependency-cache/pnpm-store + PNPM_CONFIG_CACHE_DIR: /tmp/fe-dependency-cache/pnpm-cache steps: - uses: https://github.com/actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 with: persist-credentials: false + - name: Restore and save the dependency cache + if: ${{ gitea.ref == 'refs/heads/main' }} + uses: https://github.com/actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 + with: + path: | + /opt/hostedtoolcache/node + /tmp/fe-dependency-cache + key: fe-dependencies-${{ runner.os }}-${{ runner.arch }}-${{ hashFiles('.nvmrc', 'pnpm-lock.yaml') }} + restore-keys: | + fe-dependencies-${{ runner.os }}-${{ runner.arch }}- + - name: Restore the dependency cache + if: ${{ gitea.ref != 'refs/heads/main' }} + uses: https://github.com/actions/cache/restore@0057852bfaa89a56745cba8c7296529d2fc39830 + with: + path: | + /opt/hostedtoolcache/node + /tmp/fe-dependency-cache + key: fe-dependencies-${{ runner.os }}-${{ runner.arch }}-${{ hashFiles('.nvmrc', 'pnpm-lock.yaml') }} + restore-keys: | + fe-dependencies-${{ runner.os }}-${{ runner.arch }}- - uses: https://github.com/actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 with: node-version-file: .nvmrc @@ -131,10 +179,33 @@ jobs: image: "mcr.microsoft.com/playwright:v1.62.0-noble@sha256:baed2032d533817f3dbe6425de795788430ba345e819a1201337009ba17c9d07" env: CI_RUNNER_IMAGE: "mcr.microsoft.com/playwright:v1.62.0-noble@sha256:baed2032d533817f3dbe6425de795788430ba345e819a1201337009ba17c9d07" + COREPACK_HOME: /tmp/fe-dependency-cache/corepack + PNPM_CONFIG_STORE_DIR: /tmp/fe-dependency-cache/pnpm-store + PNPM_CONFIG_CACHE_DIR: /tmp/fe-dependency-cache/pnpm-cache steps: - uses: https://github.com/actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 with: persist-credentials: false + - name: Restore and save the dependency cache + if: ${{ gitea.ref == 'refs/heads/main' }} + uses: https://github.com/actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 + with: + path: | + /opt/hostedtoolcache/node + /tmp/fe-dependency-cache + key: fe-dependencies-${{ runner.os }}-${{ runner.arch }}-${{ hashFiles('.nvmrc', 'pnpm-lock.yaml') }} + restore-keys: | + fe-dependencies-${{ runner.os }}-${{ runner.arch }}- + - name: Restore the dependency cache + if: ${{ gitea.ref != 'refs/heads/main' }} + uses: https://github.com/actions/cache/restore@0057852bfaa89a56745cba8c7296529d2fc39830 + with: + path: | + /opt/hostedtoolcache/node + /tmp/fe-dependency-cache + key: fe-dependencies-${{ runner.os }}-${{ runner.arch }}-${{ hashFiles('.nvmrc', 'pnpm-lock.yaml') }} + restore-keys: | + fe-dependencies-${{ runner.os }}-${{ runner.arch }}- - uses: https://github.com/actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 with: node-version-file: .nvmrc @@ -166,6 +237,8 @@ jobs: if: ${{ startsWith(gitea.ref, 'refs/tags/v') || (gitea.event_name == 'workflow_dispatch' && (inputs.stage == 'release' || inputs.stage == 'production' || inputs.stage == 'field')) }} runs-on: ubuntu-latest timeout-minutes: 45 + env: + RELEASE_TAG: "${{ startsWith(gitea.ref, 'refs/tags/v') && gitea.ref_name || '' }}" strategy: fail-fast: false matrix: diff --git a/CHANGELOG.md b/CHANGELOG.md index 3e351cce..f3543823 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -21,14 +21,16 @@ Gitea runner에서 merge 단계를 초록으로 만들고, worker를 늘리지 - merge / browser tests job이 Playwright 공식 이미지(`config/ci/gates.json`의 `browser-install.image`, digest 고정)에서 돈다. `@playwright/test`를 올릴 때 이 digest도 같은 버전으로 바꾼다(`tests/unit/ci-browser-image.test.ts`가 막는다). - devDependencies에서 `dependency-cruiser`가 빠진다. 그 CLI를 따로 쓰고 있었으면 다시 더한다. - 선택 runtime 제거 드릴 셋이 merge의 FE-GATE-020에서 main 단계의 새 게이트 FE-GATE-030으로 옮는다. main job 이름이 `main / self-tests and removal drills`로 바뀐다. 그 이름을 필수 검사로 걸었으면 바꾼다. 선택 runtime을 바꾸는 PR은 `scripts/verify.sh gate FE-GATE-030`을 직접 돌린다. +- merge job 셋이 runner의 actions/cache 저장소에서 Node·corepack·pnpm store와 메타데이터 캐시를 복원하고, main run만 저장한다. runner에 캐시 서버가 없으면 복원 단계가 경고만 내고 설치가 그대로 돈다. 자기 runner의 캐시 크기 상한을 확인한다(항목 하나가 압축 전 약 0.7GB, lockfile이 바뀔 때마다 새 항목). ### 보안·계약 변경 | 표시 | 변경 | 영향 경로 | 커밋 | | --- | --- | --- | --- | | [계약] | 게이트 필드 `hostEnvironment`(`"system-container"`)를 더한다. 생성기와 `scripts/verify.sh`가 그 게이트를 `scripts/run-in-system-container.sh`로 감싸고, 실행 검사는 계약이 정한 접두어로 돈 줄만 센다. FE-GATE-013에 준다 | `config/ci/gates.json`, `scripts/contracts/ci-gates.ts`, `scripts/generate-ci-workflow.ts`, `scripts/verify.sh`, `scripts/run-in-system-container.sh`, `config/ci/system-container.Dockerfile` | `1d3eb901` | -| [계약] | 게이트 FE-GATE-030 `optional-removability`(main 단계)를 더하고 FE-GATE-020에서 선택 runtime 제거 드릴 셋을 옮긴다. 정규 게이트 ID는 001..030, MAIN_READY는 029·030, 계약 보고서 `gateCount`는 29다(소유자 결정 2026-11-12) | `config/ci/gates.json`, `scripts/contracts/ci-gates.ts`, `scripts/lib/promotion-readiness.ts`, `scripts/lib/ci-contract-report.ts`, `scripts/lib/feature-scaffold-drill.ts` | `8de1403b` | +| [계약] | 게이트 FE-GATE-030 `optional-removability`(main 단계)를 더하고 FE-GATE-020에서 선택 runtime 제거 드릴 셋을 옮긴다. 정규 게이트 ID는 001..030, MAIN_READY는 029·030, 계약 보고서 `gateCount`는 29다(권하는 안으로 정함 2026-11-12, 총괄) | `config/ci/gates.json`, `scripts/contracts/ci-gates.ts`, `scripts/lib/promotion-readiness.ts`, `scripts/lib/ci-contract-report.ts`, `scripts/lib/feature-scaffold-drill.ts` | `8de1403b` | | [계약] | `browser-install` 단계에 `image`(Playwright 레지스트리 noble 태그 + digest)를 더한다. 생성기는 그 job의 container와 job env `CI_RUNNER_IMAGE`로 그리고, 단계는 글꼴만 설치한다. gate-sequence job에만 둔다 | 같은 파일, `tests/unit/ci-browser-image.test.ts` | `92abfd20` | +| [계약] | job 단계 `dependency-cache`와 CI action `cache`(actions/cache v4.3.0, 짝 백엔드와 같은 pin)를 더한다. merge job 셋에만 두고(계약이 다른 job을 거절), 생성기가 main 복원·저장과 그 밖 복원만 두 단계, job env `COREPACK_HOME`·`PNPM_CONFIG_STORE_DIR`·`PNPM_CONFIG_CACHE_DIR`로 그린다. `scripts/run-in-system-container.sh`가 그 store와 메타데이터 캐시를 컨테이너에 넘긴다(권하는 안으로 정함 2026-11-13, 총괄) | `config/ci/gates.json`, `scripts/contracts/ci-gates.ts`, `scripts/generate-ci-workflow.ts`, `scripts/run-in-system-container.sh`, `.gitea/workflows/quality-gates.yml` | `7ed0af3d` | ### 그 밖의 변경 diff --git a/config/ci/gates.json b/config/ci/gates.json index fa629cb4..594c173d 100644 --- a/config/ci/gates.json +++ b/config/ci/gates.json @@ -1993,6 +1993,9 @@ "commandIds": [ "review-a11y-manual" ], + "requiresEnvironment": [ + "RELEASE_TAG" + ], "logArtifactId": "artifact-artifacts-quality-gates-FE-GATE-028-txt", "evidenceArtifactIds": [ "artifact-docs-accessibility-route-reviews-APP-HOME-md", @@ -2158,6 +2161,9 @@ { "kind": "checkout" }, + { + "kind": "dependency-cache" + }, { "kind": "setup-node" }, @@ -2199,6 +2205,9 @@ { "kind": "checkout" }, + { + "kind": "dependency-cache" + }, { "kind": "setup-node" }, @@ -2239,6 +2248,9 @@ { "kind": "checkout" }, + { + "kind": "dependency-cache" + }, { "kind": "setup-node" }, @@ -2282,7 +2294,12 @@ "browserGateIds": [ "FE-GATE-026" ], - "environment": [], + "environment": [ + { + "name": "RELEASE_TAG", + "value": "${{ startsWith(gitea.ref, 'refs/tags/v') && gitea.ref_name || '' }}" + } + ], "steps": [ { "kind": "checkout" diff --git a/config/repository-layout.json b/config/repository-layout.json index 38523efa..9227ff8b 100644 --- a/config/repository-layout.json +++ b/config/repository-layout.json @@ -28,7 +28,8 @@ "agent-harness": "에이전트 하네스 파일(tests/unit/template-contract-documents.test.ts)", "feature-typecheck": "기능 코드와 기능 시험을 타입 검사하는 tsconfig(tests/unit/manual-code-blocks.test.ts)", "product-typecheck": "제품 사본을 타입 검사하는 tsconfig(tests/unit/product-extension-typecheck.test.ts)", - "app-typecheck": "앱 프로그램 tsconfig와 그 기반 설정(tests/unit/two-feature-install-typecheck.test.ts)" + "app-typecheck": "앱 프로그램 tsconfig와 그 기반 설정(tests/unit/two-feature-install-typecheck.test.ts)", + "dependency-cache-key": "merge job 의존성 캐시의 키를 정하는 입력(scripts/contracts/ci-gates.ts의 DEPENDENCY_CACHE)" }, "entries": [ { @@ -105,7 +106,7 @@ "kind": "tool-convention", "role": "Node 버전", "readBy": "nvm, CI", - "sets": ["fixture-copy", "secret-scan"] + "sets": ["fixture-copy", "secret-scan", "dependency-cache-key"] }, { "path": ".release", @@ -285,7 +286,7 @@ "kind": "tool-convention", "role": "잠금 파일", "readBy": "pnpm, 공급망 생성", - "sets": ["fixture-copy", "secret-scan", "scale-source", "package-manifest"] + "sets": ["fixture-copy", "secret-scan", "scale-source", "package-manifest", "dependency-cache-key"] }, { "path": "pnpm-workspace.yaml", diff --git a/docs/adr/VD-04-native-form-facade.md b/docs/adr/VD-04-native-form-facade.md index 859500a4..083dcc87 100644 --- a/docs/adr/VD-04-native-form-facade.md +++ b/docs/adr/VD-04-native-form-facade.md @@ -73,3 +73,7 @@ React Hook Form과 Zod resolver를 평가한다. rollback 시 reference page는 이전 직접 form/layout으로 돌아갈 수 있다. application input과 outbound gateway 계약은 유지되며, form facade와 template commit은 독립적으로 되돌릴 수 있다. + +## 보완 + +- 2026-11-12: 결정 5(409 conflict는 validation으로 바꾸지 않는다)는 기능이 선언하지 않은 409에 적용된다. 기능이 `useAppForm`의 `refusalMessages`로 선언한 쓰기 전 거절은 409라도 기능의 문구로 필드나 오류 요약에 보이고, 폼은 다음 저장을 받는다(1103/03-01, 매뉴얼 02 결정표 4절). 그 밖의 409는 그대로 충돌이고, `mutation` 옵션을 준 폼은 그 안내를 입력 오류 요약이 아니라 `FormSaveFeedback`에 보인다(1112/04-02). diff --git a/docs/manual/01-add-a-feature.md b/docs/manual/01-add-a-feature.md index a49d0e6b..07093512 100644 --- a/docs/manual/01-add-a-feature.md +++ b/docs/manual/01-add-a-feature.md @@ -579,6 +579,7 @@ export function useInvoiceListFilters(): InvoiceListSearch { - 페이지 템플릿. [02 결정표 6절](02-decision-tables.md#6-페이지-템플릿) - 쓰기가 있으면 결과 불명 화면. `AsyncSurface`의 `onReconcileUnknownEffect`(확인), `onResendUnknownEffect`(같은 키로 다시 보내기). 다시 보내기 버튼은 다시 보내도 되는 요청(`KEYED`, `IDEMPOTENT`. 뮤테이션 정책의 `resendSafe`)에만 그려진다. `NEVER` 쓰기는 확인만 남는다. 폼 밖에서 `mutation.submit`을 부르는 화면도 `NEVER` 쓰기의 같은 입력을 다시 보낼 수 없다. 훅이 `DUPLICATE_IN_FLIGHT`(code `UNKNOWN_EFFECT_PENDING`)로 거절한다. `AsyncSurface`에 손으로 만든 상태를 넘기면 재전송 버튼은 그려지지 않는다(코디네이터의 `state`를 넘긴다). +- 폼으로 저장하면 결과 불명 화면을 직접 잇지 않는다. `useAppForm`에 `mutation`과 저장 뒤 할 일(`onSaved`)을 주고 피드백 자리에 `FormSaveFeedback`을 둔다. 확인·재전송, 결과 불명 동안 새 저장 막기, 페이지를 떠난 뒤 끝난 저장이 아무 데도 옮기지 않는 것을 폼이 맡는다. - 폼이면 서버 필드 오류를 받을 필드(`useAppForm`의 `allowedServerFields`). 짝 백엔드는 필드 검증 거절을 400 `VALIDATION_FAILED`와 `details[{field, code}]`로 보낸다(422가 아니다). 공유 MSW 시나리오에는 짝 백엔드가 보내지 않는 `validation-422`만 있고, Envelope operation에서 그 답은 결과 불명이다. 짝 백엔드 모양의 필드 오류 테스트는 생성된 작성 폼 테스트(`-create-page.test.tsx`)처럼 400 본문을 손으로 적는다. ② **기준** diff --git a/docs/manual/02-decision-tables.md b/docs/manual/02-decision-tables.md index 56da9ac5..529fbabf 100644 --- a/docs/manual/02-decision-tables.md +++ b/docs/manual/02-decision-tables.md @@ -185,7 +185,7 @@ context는 URL 앞부분 하나(라우트 루트)를 가진다. 그 아래 기 - 적을 수 없는 code: `IDEMPOTENT_*`, `IDEMPOTENCY_*`. 멱등성 응답은 백엔드 표가 정한다. 적으면 계약 조립이 `refusedBeforeWrite cannot declare ...`로 거부한다. `responseEnvelope: "ENVELOPE_V1"`가 아닌 operation에 적어도 거부한다(`refusedBeforeWrite needs responseEnvelope ENVELOPE_V1 ...`). - 계약 문서 6.1절이 "쓰기 뒤 가능"으로 둔 플랫폼 code(`BAD_PARAMETER`, `MAPPING_FAILED`, `DB_UNIQUE_VIOLATION` 등 `DB_*`, `LOCK_ACQUISITION_TIMEOUT`, fileserver code)도 적을 수 없다. 폼을 막는 400 `BAD_PARAMETER`나 409 `DB_UNIQUE_VIOLATION`은 어느 층에서든, 트랜잭션 안에서도 나온다. 적으면 계약 조립이 `refusedBeforeWrite cannot declare ...; contract 6.1 reads this platform code as possibly raised after the write`로 거부한다. - 거절 이유를 필드 옆에 보이려면 `mapProblem`이 그 code를 `VALIDATION_REJECTED`와 필드 목록으로 돌려준다. 선언 없이 `mapProblem`만 두면 필드 오류는 보이지만 저장 버튼은 꺼진 채다. - - 거절 이유를 기능의 말로 보이려면 `useAppForm`의 `refusalMessages`에 code별로 기능 catalog의 메시지 키와 필드를 적는다(예: `{ POSTER_ALREADY_EXISTS: { field: "name", message: "poster.form.nameTaken" } }`). 적용 안 됨(`NOT_APPLIED`)으로 끝난 실패만 읽는다. 그 code는 필드 오류(필드가 없으면 오류 요약)가 되고, 결과는 `validation-error`다. 적지 않으면 선언한 400은 "요청을 처리할 수 없습니다" + 지원 안내, 409는 충돌 문구가 보인다. 결과 불명은 code와 상관없이 결과 불명으로 남는다. + - 거절 이유를 기능의 말로 보이려면 `useAppForm`의 `refusalMessages`에 code별로 기능 catalog의 메시지 키와 필드를 적는다(예: `{ POSTER_ALREADY_EXISTS: { field: "name", message: "poster.form.nameTaken" } }`). 적용 안 됨(`NOT_APPLIED`)으로 끝난 실패만 읽는다. 그 code는 필드 오류(필드가 없으면 오류 요약)가 되고, 결과는 `validation-error`다. 적지 않으면 선언한 400은 "요청을 처리할 수 없습니다" + 지원 안내, 409는 충돌 문구가 보인다. 결과 불명은 code와 상관없이 결과 불명으로 남는다. 필드 이름이 붙은 실패라도 결과 불명(`MAYBE_APPLIED`)이면 필드 오류가 아니라 결과 불명으로 보인다. 같은 키 재전송이 쓰기 전에 거절되면, `mutation`을 준 폼은 그 안내를 입력 오류 요약이 아니라 결과 불명 표면(`FormSaveFeedback`)에 보인다. **503 `IDEMPOTENCY_UNAVAILABLE`는 `NOT_APPLIED`로 분류하지 않는다.** diff --git a/docs/manual/reference/patterns.md b/docs/manual/reference/patterns.md index 6fa3962b..69c1b92a 100644 --- a/docs/manual/reference/patterns.md +++ b/docs/manual/reference/patterns.md @@ -96,7 +96,7 @@ const search = (q: string) => | 쿼리 바인딩 | `src/contracts/server-state.ts`의 `bindQuery`, `src/presentation/adapters/query/application-query.ts` | 생성 뼈대 `presentation/use--items.ts` | profile ID (실행 때). `owner`·`operationId`는 읽는 곳이 없는 `@deprecated` 칸이라 적지 않는다 | | 무효화 topic | `src/contracts/query-invalidation.ts` | 생성 뼈대 계약 `invalidation` | 조립(중복, 고아 topic) | | 멱등 키 쓰기 | V3 `retrySemantics: "KEYED"`, `commandRecovery`, 뮤테이션 정책(`src/contracts/server-state.ts`의 `commandMutationIdentity`로 operation ID와 키 여부를 descriptor에서 받는다) | 쓰기 slice `--keyed`(`contracts/-contract-contribution.ts`, `presentation/use--create.ts`) | 계약 조립(복구 descriptor 필수), 타입(descriptor 상수 이름, 손으로 적은 operation ID는 `MutationOperationId`가 아니다), 기능 테스트 | -| 결과 불명 화면 | `src/presentation/components/async-surface.tsx`의 `onReconcileUnknownEffect`, `onResendUnknownEffect` | 쓰기 slice `presentation/-create-page.tsx` | 기능 테스트만(쓰기 slice는 `-create-page.test.tsx`) | +| 결과 불명 화면 | `src/presentation/components/async-surface.tsx`의 `onReconcileUnknownEffect`, `onResendUnknownEffect`. 폼으로 저장하면 아래 「폼」 행의 `FormSaveFeedback`이 이 둘을 잇는다 | 쓰기 slice `presentation/-create-page.tsx` | 기능 테스트(쓰기 slice는 `-create-page.test.tsx`), `tests/component/form-foundation.test.tsx` | | 수정·삭제 명령 | 같은 V3 계약 (`PUT`, `PATCH`, `DELETE`) | 없음 (쓰기 slice는 작성 명령만 만든다) | — | | 낙관적 갱신 | `useApplicationMutation`의 `optimistic` 옵션 (`application-query.ts`) | 없음 | 런타임 테스트만 | | 페이지 넘김 | `src/adapters/query-cache/index.ts`의 `createCursorPaginationRuntime` | 없음 (생성 뼈대 목록은 첫 페이지와 `meta.page.total`만 읽는다) | 런타임 테스트만 | @@ -108,7 +108,7 @@ const search = (q: string) => |---|---|---|---| | 페이지 템플릿 | `src/presentation/templates/page-templates.tsx` | 생성 뼈대 `CollectionPage`, 쓰기 slice `DetailPage`·`FormPage` | `page-templates-own-layout-only` | | 비동기 상태 화면 | `src/presentation/components/async-surface.tsx`의 `AsyncSurface` | 생성 뼈대 목록 페이지 | 페이지 테스트 | -| 폼 | `src/presentation/forms/use-app-form.ts`의 `useAppForm` | 쓰기 slice `presentation/-form.ts`와 `-create-page.tsx` | 페이지 테스트(서버 필드 오류, 이탈 확인) | +| 폼 | `src/presentation/forms/use-app-form.ts`의 `useAppForm`. mutation으로 저장하는 폼은 `mutation` 옵션을 주고 피드백 자리에 `FormSaveFeedback`(`src/presentation/forms/form-components.tsx`)을 둔다. 결과 불명 동안 새 저장 막기, 「변경됨으로 확인」, 같은 키 재전송, 다른 저장이 도는 동안의 표시, 마운트된 동안만 저장 뒤 이동(`onSaved`, `FormSaveFeedback`의 `onConfirmed`)을 폼이 맡는다 | 쓰기 slice `presentation/-form.ts`와 `-create-page.tsx` | 페이지 테스트(서버 필드 오류, 이탈 확인), `tests/component/form-foundation.test.tsx` | | 화면 문구 | `src/presentation/i18n/index.ts`, 기능 문구 catalog | 생성 뼈대 `contracts/-message-catalog.ts` | `lint`(문구 literal), `check:i18n`(ko-KR·en-US 키) | | 권한 분기 | 라우트 `access`, 서버 403 → 실패 | 코드 조각: [01 문서 10단계](../01-add-a-feature.md#10단계-테스트)의 403 페이지 테스트 `tests/features//-forbidden.test.tsx` | 가드 테스트. 역할·권한 힌트 예제는 없음 | diff --git a/docs/operations/ci-quality-gates.md b/docs/operations/ci-quality-gates.md index 875cdc37..7c7ab0f4 100644 --- a/docs/operations/ci-quality-gates.md +++ b/docs/operations/ci-quality-gates.md @@ -8,10 +8,21 @@ 출력을 거절한다. `corepack pnpm check:ci`는 산출물 schema 검사, 타입이 있는 계약 검사기, 이 workflow drift 검사를 돈다. merge 단계는 job 셋(`merge_static`, `merge_test`, `merge_browser`)으로 돌고 job마다 설치를 한 번 한다. 게이트마다 ID 이름의 step이 하나씩 -있고, 실패한 게이트가 다음 게이트를 건너뛰게 하지 않는다. 검사기 자신의 음성 fixture와 +있고, 실패한 게이트가 다음 게이트를 건너뛰게 하지 않는다. + +merge job 셋만 의존성 캐시를 쓴다(권하는 안으로 정함 2026-11-13, 총괄). setup-node 앞에서 +Node toolcache, corepack이 받은 pnpm, pnpm store와 메타데이터 캐시를 `.nvmrc`와 +`pnpm-lock.yaml` 해시 키로 복원한다. 저장은 main run만 한다. 캐시 항목은 다음 run이 믿는 +입력이다. pnpm은 같은 lockfile의 공급망 검증 기록이 캐시에 있으면 검증을 다시 하지 않는다. +그래서 브랜치 run은 복원만 한다. frozen install은 캐시가 맞든 없든 늘 돈다. 항목이 없거나 +깨지면 pnpm이 모자란 패키지만 내려받고 node_modules는 같다. FE-GATE-013의 시스템 컨테이너도 +같은 store와 메타데이터 캐시를 받는다. release·promotion·provider job은 공급망 증거를 +만들므로 매번 새로 설치한다. 이 규칙은 `scripts/contracts/ci-gates.ts`의 `DEPENDENCY_CACHE`와 +계약 검사가 지킨다. runner의 캐시 저장소는 짝 백엔드와 함께 쓰고 크기 상한이 있다(platform-core +`infrastructure/ci/gitea-runner/config.yaml`). 검사기 자신의 음성 fixture와 gating 검사는 branch에 push한 뒤 main 단계(`main_gate`, FE-GATE-029)에서 돈다. 선택 runtime 제거 드릴 셋(FE-GATE-030)도 main 단계에서 돈다. PR runner 시간 약 30분 가운데 7분쯤이라 -merge에서 뺐고, 실패하면 main이 빨강이 되어 다음 PR이 고친다(소유자 결정 2026-11-12). release와 +merge에서 뺐고, 실패하면 main이 빨강이 되어 다음 PR이 고친다(권하는 안으로 정함 2026-11-12, 총괄). release와 production 게이트는 matrix check로 남는다. 실패를 무시하는(soft-fail) 연결은 없다. 같은 PR이나 같은 브랜치에 새 push가 오면 workflow `concurrency`가 앞 run을 취소한다. Gitea는 앞 run의 대기 중인 job은 언제나, 돌고 있는 job은 `cancel-in-progress`가 참일 때 취소한다. @@ -137,6 +148,10 @@ full commit ID와 commit timestamp를 한 번 읽어 `SOURCE_DATE_EPOCH`를 유 release manifest도 같은 build ID, commit SHA, release ID와 timestamp를 가져야 한다. +`release_gate` job은 tag run이면 그 tag 이름(예 `v1.4.0`)을 `RELEASE_TAG`로 준다. +FE-GATE-028이 이 값을 요구한다(`requiresEnvironment`). tag run이 아니면(브랜치에서 수동으로 +돌린 release 단계) 값이 비어 게이트가 `missing required environment: RELEASE_TAG`로 실패한다. + Release tier의 `immutable_build`는 `dist`의 hidden `.vite` entries, raw `pnpm-lock.yaml`, build/module inventory와 local release/security evidence를 한 번 생성해 run ID/attempt로 구분된 archive로 게시한다. Raw lock bytes의 SHA-256은 diff --git a/docs/work/reference/decisions.md b/docs/work/reference/decisions.md index d272ea32..b5bab5de 100644 --- a/docs/work/reference/decisions.md +++ b/docs/work/reference/decisions.md @@ -70,7 +70,8 @@ | round9 R9-D10 예산과 advisory | 2026-11-12 | 권하는 안으로 정함(2026-11-12, 총괄). D1을 먼저 정한다: zod·react-router 갱신이 지금 초기 JS 예산 안에 들어가므로 갱신하고, 드릴을 다시 재서 D9 규칙으로 예산을 정한다. 버린 안: 예산만 먼저 내림 | 같음, 1106/15-01, 1103/13-03 | | round9 R9-D11 `@a11y` 두 번 실행 | 2026-11-12 | 권하는 안으로 정함(2026-11-12, 총괄). 그대로 둔다. 게이트마다 증거를 새로 만드는 계약이다. 결함 아님으로 닫는다. 버린 안: FE-GATE-009가 FE-GATE-008 결과를 쓰기 | 같음, 1112/03-10 | | round9 R9-D12 CSS·라우트 lazy 합 예산 | 2026-11-12 | 권하는 안으로 정함(2026-11-12, 총괄). 지금 값을 기록만 하고 예산은 두지 않는다. 다시 볼 때: 첫 공개 기능 라우트 lab. 버린 안: 예산 신설 | 같음, 1101/15-03 | -| 결정 p 선택 runtime 제거 드릴을 main 단계로 | 2026-11-12 | FE-GATE-020의 선택 runtime 제거 드릴 셋(optional recipe, browser file/storage, realtime)을 새 게이트 FE-GATE-030으로 떼어 main 단계(`main_gate`)에서 돌린다. 기능 드릴(샘플 제거, scaffold)은 merge에 남는다. 이유: runner PR 1회 약 30분 가운데 7분쯤이고, worker를 늘리지 않고 merge 25분 목표에 닿는 길이 이것뿐이었다. 대가: 그 셋의 회귀를 병합 뒤 main run에서 본다. main이 빨강이면 다음 PR이 고친다. 짝 백엔드가 무거운 lane을 nightly로 옮긴 것과 같은 모양이다. 재검토: runner가 늘거나 드릴이 빨라져 merge에 다시 넣어도 25분 안이면 되돌린다 | 소유자 결정 p(2026-11-12, design-docs `template-program/README.md` 5절, W2-FE의 O1 권하는 안 채택) | +| 결정 p 선택 runtime 제거 드릴을 main 단계로 | 2026-11-12 | FE-GATE-020의 선택 runtime 제거 드릴 셋(optional recipe, browser file/storage, realtime)을 새 게이트 FE-GATE-030으로 떼어 main 단계(`main_gate`)에서 돌린다. 기능 드릴(샘플 제거, scaffold)은 merge에 남는다. 이유: runner PR 1회 약 30분 가운데 7분쯤이고, worker를 늘리지 않고 merge 25분 목표에 닿는 길이 이것뿐이었다. 대가: 그 셋의 회귀를 병합 뒤 main run에서 본다. main이 빨강이면 다음 PR이 고친다. 짝 백엔드가 무거운 lane을 nightly로 옮긴 것과 같은 모양이다. 재검토: runner가 늘거나 드릴이 빨라져 merge에 다시 넣어도 25분 안이면 되돌린다 | 권하는 안으로 정함(2026-11-12, 총괄): 백엔드 nightly lane과 같은 모양(design-docs `template-program/README.md` 5절 p, w2-fe-2가 올린 O1) | +| 의존성 캐시는 merge job만 | 2026-11-13 | merge job 셋(`merge_static`·`merge_test`·`merge_browser`)만 Node toolcache·corepack·pnpm store와 메타데이터 캐시를 `.nvmrc`·`pnpm-lock.yaml` 해시 키로 복원하고, 저장은 main run만 한다. release·promotion·provider job은 공급망 증거를 만들므로 매번 새로 설치한다. 이유: worker를 늘리지 않고 job마다 되풀이하던 내려받기와 공급망 검증 요청을 없앤다. 캐시가 없거나 깨져도 frozen install이 같은 node_modules를 만든다. 짝 백엔드의 JDK·Gradle·Trivy 캐시와 같은 저장 규칙이다. 버린 안: CI 이미지에 의존성을 굽기(레지스트리 쓰기 토큰이 든다). 규칙의 정본은 `scripts/contracts/ci-gates.ts`의 `DEPENDENCY_CACHE` | 권하는 안으로 정함(2026-11-13, 총괄): 의존성 캐시는 merge job만, 공급망 증거 job은 매번 새로 설치 | | 구조·기술 결정 기록 | 2026-07-26~ | `VD-01`~(빈 번호 있음) | `docs/adr/` | ## 3. 결정 대기 쓰는 법 diff --git a/docs/work/reference/structure.md b/docs/work/reference/structure.md index 363f37a4..03d3319e 100644 --- a/docs/work/reference/structure.md +++ b/docs/work/reference/structure.md @@ -114,7 +114,7 @@ src/ 최상위 폴더 ── 역할: docs/architecture/layers.md 표 ## 12. 제거 가능성 -지울 수 있는 단위는 드릴이 지킨다. 기능 드릴(샘플 제거, 생성 기능의 scaffold·제거)은 merge 게이트 FE-GATE-020, 선택 runtime 제거 드릴 셋(optional recipe, browser file/storage, realtime)은 main 단계 FE-GATE-030이다(소유자 결정 2026-11-12). 드릴 목록은 `config/ci/gates.json`의 두 게이트 `commandIds`다. 선택 runtime을 바꾼 PR은 merge에서 FE-GATE-030이 돌지 않으니 `scripts/verify.sh gate FE-GATE-030`을 직접 돌린다. +지울 수 있는 단위는 드릴이 지킨다. 기능 드릴(샘플 제거, 생성 기능의 scaffold·제거)은 merge 게이트 FE-GATE-020, 선택 runtime 제거 드릴 셋(optional recipe, browser file/storage, realtime)은 main 단계 FE-GATE-030이다(권하는 안으로 정함 2026-11-12, 총괄). 드릴 목록은 `config/ci/gates.json`의 두 게이트 `commandIds`다. 선택 runtime을 바꾼 PR은 merge에서 FE-GATE-030이 돌지 않으니 `scripts/verify.sh gate FE-GATE-030`을 직접 돌린다. - 구조를 바꾸면 드릴을 돌린다. 드릴 fixture가 복사하는 목록(`scripts/lib/removal-fixture.ts`, 이 목록 하나만 쓴다)이 바뀐 구조를 아는지 본다. 그 목록에 `README.md`·`CHANGELOG.md`가 없어 드릴 넷 중 셋이 항상 실패한 일이 있다(결함 패턴 G11). - 드릴은 오래 걸린다(desktop 2026-11-13 실측: FE-GATE-020과 FE-GATE-030 합쳐 약 10분 30초). desktop에서 잠금 아래 돌린다. diff --git a/scripts/contracts/ci-gates.ts b/scripts/contracts/ci-gates.ts index 86014ffd..71499d29 100644 --- a/scripts/contracts/ci-gates.ts +++ b/scripts/contracts/ci-gates.ts @@ -4,6 +4,7 @@ import path from "node:path"; import { z } from "zod"; import { DEPENDENCY_ADVISORIES_RECORD_PATH } from "../lib/dependency-advisories.ts"; +import { selectRepositoryPaths } from "../lib/repository-layout.ts"; import { PROMOTION_FORMULA } from "../lib/promotion-readiness.ts"; import { RELEASE_CANDIDATE_EVIDENCE_PATHS, @@ -39,6 +40,7 @@ const ciActionRegistrySchema = z setupNode: ciActionRegistrationSchema, uploadArtifact: ciActionRegistrationSchema, downloadArtifact: ciActionRegistrationSchema, + cache: ciActionRegistrationSchema, }) .strict() .readonly(); @@ -78,6 +80,12 @@ export const CI_ACTION_REGISTRY = parseCiActionRegistry({ revision: "75635f32b4c1c41c4b3d64e8f85210112ed4c9c7", version: "v4 branch", }, + // The same pin as the paired backend's JDK, Gradle and Trivy caches. + cache: { + repository: "https://github.com/actions/cache", + revision: "0057852bfaa89a56745cba8c7296529d2fc39830", + version: "v4.3.0", + }, }); const actionIdByStepKind = Object.freeze({ @@ -85,6 +93,7 @@ const actionIdByStepKind = Object.freeze({ "setup-node": "setupNode", upload: "uploadArtifact", download: "downloadArtifact", + "dependency-cache": "cache", } as const satisfies Readonly>); export function resolveCiActionUses(actionId: CiActionId): string { @@ -93,6 +102,42 @@ export function resolveCiActionUses(actionId: CiActionId): string { return `${action.repository}@${action.revision}`; } +/** An action a registered repository holds below its root (`actions/cache/restore`), at the same pin. */ +export function resolveCiSubActionUses(actionId: CiActionId, subpath: "restore"): string { + const action = CI_ACTION_REGISTRY[actionId]; + if (!action) throw new TypeError(`unknown CI action: ${String(actionId)}`); + return `${action.repository}/${subpath}@${action.revision}`; +} + +/** + * Decision (2026-11-13, lead): the dependency cache is for the merge jobs + * only; the jobs that produce supply-chain evidence install fresh every time + * (docs/work/reference/decisions.md). A merge job restores the Node toolcache, the corepack + * download and pnpm's store and metadata cache (with its record of the + * lockfile's supply-chain verification) before setup-node, keyed by + * `.nvmrc` and the lockfile. Only a run on main saves an entry, the paired + * backend's rule for its caches: an entry is trusted input to the next run + * (the verification record lets pnpm skip the check), so a branch must not + * write one. The frozen install always runs after it: a missing or damaged + * entry only makes pnpm download what it lacks, and node_modules is the same + * (desktop, 2026-11-13: cold 13.9 s, warm 1.6 s, 40 broken store and 40 + * broken metadata files 3.6 s with 27 packages fetched again; the same tree + * hash in all five installs). + */ +export const DEPENDENCY_CACHE = Object.freeze({ + keyPrefix: "fe-dependencies-${{ runner.os }}-${{ runner.arch }}-", + // `.nvmrc` and `pnpm-lock.yaml` (config/repository-layout.json). + keyInputs: selectRepositoryPaths("dependency-cache-key"), + paths: Object.freeze(["/opt/hostedtoolcache/node", "/tmp/fe-dependency-cache"] as const), + environment: Object.freeze([ + Object.freeze({ name: "COREPACK_HOME", value: "/tmp/fe-dependency-cache/corepack" }), + Object.freeze({ name: "PNPM_CONFIG_STORE_DIR", value: "/tmp/fe-dependency-cache/pnpm-store" }), + Object.freeze({ name: "PNPM_CONFIG_CACHE_DIR", value: "/tmp/fe-dependency-cache/pnpm-cache" }), + ]), + /** The jobs that may hold the step: the three merge jobs. */ + jobIds: Object.freeze(["merge_static", "merge_test", "merge_browser"] as const), +}); + export function resolveCiStepActionUses(stepKind: string): string | null { const actionId = actionIdByStepKind[stepKind as keyof typeof actionIdByStepKind]; return actionId ? resolveCiActionUses(actionId) : null; @@ -333,6 +378,7 @@ const environmentBindingSchema = z const checkoutStep = z.object({ kind: z.literal("checkout") }).strict(); const setupNodeStep = z.object({ kind: z.literal("setup-node") }).strict(); const frozenInstallStep = z.object({ kind: z.literal("frozen-install") }).strict(); +const dependencyCacheStep = z.object({ kind: z.literal("dependency-cache") }).strict(); /** * `image`: the job runs in Playwright's own image for the pinned * @playwright/test version, which already holds the browsers and their OS @@ -405,6 +451,7 @@ const deployStep = z const jobStepSchema = z.discriminatedUnion("kind", [ checkoutStep, + dependencyCacheStep, setupNodeStep, frozenInstallStep, browserInstallStep, @@ -817,6 +864,16 @@ function validateContractSemantics( } } validateJobStepKinds(job, issue); + if (job.steps.some(({ kind }) => kind === "dependency-cache")) { + if (!(DEPENDENCY_CACHE.jobIds as readonly string[]).includes(job.id)) { + issue(`the dependency cache is for the merge jobs only: ${job.id}`); + } + for (const { name } of DEPENDENCY_CACHE.environment) { + if (job.environment.some((binding) => binding.name === name)) { + issue(`job ${job.id} binds ${name}, which its dependency cache sets`); + } + } + } for (const step of job.steps) { const uses = resolveCiStepActionUses(step.kind); if (uses && !/^https:\/\/github\.com\/[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+@[0-9a-f]{40}$/u.test(uses)) { @@ -910,9 +967,9 @@ function validateContractSemantics( } } const expectedStepKinds: Readonly> = { - merge_static: ["checkout", "setup-node", "frozen-install", "run-gate", "upload"], - merge_test: ["checkout", "setup-node", "frozen-install", "run-gate", "upload"], - merge_browser: ["checkout", "setup-node", "frozen-install", "browser-install", "run-gate", "upload"], + merge_static: ["checkout", "dependency-cache", "setup-node", "frozen-install", "run-gate", "upload"], + merge_test: ["checkout", "dependency-cache", "setup-node", "frozen-install", "run-gate", "upload"], + merge_browser: ["checkout", "dependency-cache", "setup-node", "frozen-install", "browser-install", "run-gate", "upload"], release_gate: ["checkout", "setup-node", "frozen-install", "browser-install", "run-gate", "upload"], immutable_build: ["checkout", "setup-node", "frozen-install", "run-gate", "archive-candidate", "upload", "upload"], vulnerability_provider: ["checkout", "setup-node", "frozen-install", "download", "run-provider", "validate-provider-evidence", "upload"], @@ -934,7 +991,13 @@ function validateContractSemantics( merge_static: [], merge_test: [], merge_browser: [], - release_gate: [], + release_gate: [ + // 1112/05-01 (R9-D7, release tag). FE-GATE-028 compares each signed + // record's Release ID with the tag being released. A run that is not a + // tag run (a release stage dispatched on a branch) gets an empty value, + // and run-ci-gate.ts fails the gate on it. + { name: "RELEASE_TAG", value: "${{ startsWith(gitea.ref, 'refs/tags/v') && gitea.ref_name || '' }}" }, + ], immutable_build: [ // FE-GATE-027 admits the built artifact to a named environment, so both // the profile it was built from and the destination it is claimed for are @@ -1324,7 +1387,7 @@ function validateJobStepKinds( ): void { const allowed: Readonly["kind"], ReadonlySet>> = { "gate-matrix": new Set(["checkout", "setup-node", "frozen-install", "browser-install", "download", "extract", "run-gate", "upload"]), - "gate-sequence": new Set(["checkout", "setup-node", "frozen-install", "browser-install", "run-gate", "upload"]), + "gate-sequence": new Set(["checkout", "dependency-cache", "setup-node", "frozen-install", "browser-install", "run-gate", "upload"]), "gate-single": new Set(["checkout", "setup-node", "frozen-install", "run-gate", "upload"]), immutable: new Set(["checkout", "setup-node", "frozen-install", "run-gate", "archive-candidate", "upload"]), provider: new Set(["checkout", "setup-node", "frozen-install", "download", "extract", "run-provider", "validate-provider-evidence", "upload"]), diff --git a/scripts/create-feature-write-slice.ts b/scripts/create-feature-write-slice.ts index bf1367b5..50d6b944 100644 --- a/scripts/create-feature-write-slice.ts +++ b/scripts/create-feature-write-slice.ts @@ -589,26 +589,21 @@ export default function ${pascal}DetailPage() { export function renderCreatePage({ names, routeId, write }: SliceShape): string { const { base, camel, pascal, upper } = names; - return `import { useCallback, useEffect, useRef } from "react"; -import { Link, useNavigate } from "react-router-dom"; + return `import { Link, useNavigate } from "react-router-dom"; -import type { Result } from "../../../contracts/result.ts"; import { - AsyncSurface, Button, DirtyNavigationDialog, ErrorSummary, Form, FormActions, - FormFailureStatus, FormField, FormPage, + FormSaveFeedback, useAppForm, useDirtyNavigationGuard, } from "../../../presentation/design-system/index.ts"; import { useLocale } from "../../../presentation/i18n/index.ts"; -import type { ${pascal}CreateCommand } from "../application/${base}-feature-api.ts"; -import type { ${pascal}ItemView } from "../contracts/${base}-mapper.ts"; import { ${upper}_FORM_DEFAULTS, ${camel}FormSchema, @@ -634,63 +629,29 @@ export default function ${pascal}CreatePage() { name: message("${camel}.form.name"), } satisfies Record; const mutation = use${pascal}Create(); - // A save outlives this page when the user leaves while it runs. Ending - // then, it does not take them to its item or the list (1106/08-02). - const mounted = useRef(false); - useEffect(() => { - mounted.current = true; - return () => { - mounted.current = false; - }; - }, []); - const openSaved = useCallback( - (outcome: Result<${pascal}ItemView> | null) => { - if (outcome?.ok && mounted.current) { - void navigate( - ${camel}RouteUrl("${write.detail.routeId}", { - params: { ${write.idParam}: outcome.value.itemId }, - }), - ); - } - return outcome; - }, - [navigate], - ); - const submit = useCallback( - async (command: ${pascal}CreateCommand) => { - const outcome = await mutation.submit(command); - openSaved(outcome); - return outcome; - }, - [mutation, openSaved], - ); + // The form holds the rules of a save through the mutation: no new save + // while one is unknown or another runs, confirm and resend of an unknown + // one, and what the page does after a save only while it is still open + // (useAppForm \`mutation\` and \`onSaved\`, FormSaveFeedback). const form = useAppForm({ schema: ${camel}FormSchema, defaultValues: ${upper}_FORM_DEFAULTS, allowedServerFields: ["name"], mapToCommand: to${pascal}CreateCommand, - submit, + submit: mutation.submit, + mutation, + onSaved: (item) => { + void navigate( + ${camel}RouteUrl("${write.detail.routeId}", { + params: { ${write.idParam}: item.itemId }, + }), + ); + }, }); - const effectUnknown = mutation.state.indicator === "mutation-effect-unknown"; - const blocked = effectUnknown || mutation.state.indicator === "mutation-pending"; - // A save this form did not start holds the coordinator (one left running - // when the user came back, or the check behind "confirm applied"): the save - // is off and the feedback says a save is running (1105/08-04). - const otherSaveRunning = mutation.state.indicator === "mutation-pending" && !form.pending; const guard = useDirtyNavigationGuard(form.dirty && !form.pending); return ( -
{ - if (blocked) { - event.preventDefault(); - return; - } - void form.submitForm(event); - }} - > + void form.submitForm(event)}> {message("${camel}.list.title")}} @@ -715,38 +676,21 @@ export default function ${pascal}CreatePage() { type="submit" pending={form.pending} pendingLabel={message("${camel}.form.saving")} - disabled={effectUnknown || otherSaveRunning} + disabled={form.effectUnknown || form.otherSaveRunning} > {message("${camel}.form.save")} } feedback={ - form.failure ? ( - void form.submitForm() : undefined} - /> - ) : effectUnknown ? ( - { - void mutation.reconcileUnknownEffect(resolution).then(() => { - form.settleApplied(); - if (mounted.current) void navigate(${camel}RouteUrl("${routeId}")); - }); - }} - // Drawn only for a request with a key (a KEYED command). - onResendUnknownEffect={() => { - void form.resendUnknown(async () => openSaved(await mutation.resendUnknownEffect())); - }} - /> - ) : otherSaveRunning && form.result !== "effect-unknown" ? ( - - ) : null + { + void navigate(${camel}RouteUrl("${routeId}")); + }} + /> } guard={} /> diff --git a/scripts/generate-ci-workflow.ts b/scripts/generate-ci-workflow.ts index 86b0aef0..50a68b1e 100644 --- a/scripts/generate-ci-workflow.ts +++ b/scripts/generate-ci-workflow.ts @@ -11,9 +11,11 @@ import { fileURLToPath } from "node:url"; import path from "node:path"; import { + DEPENDENCY_CACHE, indexCiGateContract, loadCiGateContract, resolveCiStepActionUses, + resolveCiSubActionUses, type CiGateContract, type CiWorkflowJob, type CiWorkflowStep, @@ -234,9 +236,16 @@ function renderJob( const jobEnvironment = job.environment.filter((binding) => !isStepScopedSecret(job, binding)); // The build records the image it ran in (scripts/lib/build-environment.ts): // a job in its own image names that one, not the runner label's. + // Every pnpm and corepack call of the job reads the cached directories, the + // install and the system container's own install alike. + const cacheEnvironment = job.steps.some(({ kind }) => kind === "dependency-cache") + ? DEPENDENCY_CACHE.environment + : []; const environmentLines = [ ...(image ? [` CI_RUNNER_IMAGE: ${yamlScalar(image)}`] : []), - ...jobEnvironment.map((binding) => ` ${binding.name}: ${yamlScalar(binding.value)}`), + ...[...cacheEnvironment, ...jobEnvironment].map( + (binding) => ` ${binding.name}: ${yamlScalar(binding.value)}`, + ), ]; if (environmentLines.length > 0) lines.push(" env:", ...environmentLines); if (job.kind === "gate-matrix") { @@ -316,6 +325,29 @@ function renderStep( " with:", " node-version-file: .nvmrc", ]; + case "dependency-cache": { + // DEPENDENCY_CACHE: main restores and saves, every other ref restores. + // The frozen install after it runs either way. + const inputs = DEPENDENCY_CACHE.keyInputs.map((file) => `'${file}'`).join(", "); + const cache = [ + " with:", + " path: |", + ...DEPENDENCY_CACHE.paths.map((cachePath) => ` ${cachePath}`), + ` key: ${DEPENDENCY_CACHE.keyPrefix}\${{ hashFiles(${inputs}) }}`, + " restore-keys: |", + ` ${DEPENDENCY_CACHE.keyPrefix}`, + ]; + return [ + " - name: Restore and save the dependency cache", + " if: ${{ gitea.ref == 'refs/heads/main' }}", + ` uses: ${requiredStepActionUses(step.kind)}`, + ...cache, + " - name: Restore the dependency cache", + " if: ${{ gitea.ref != 'refs/heads/main' }}", + ` uses: ${resolveCiSubActionUses("cache", "restore")}`, + ...cache, + ]; + } case "frozen-install": return [ " - name: Frozen install", diff --git a/scripts/lib/repository-layout.ts b/scripts/lib/repository-layout.ts index a3e0bb60..6a5b8f6b 100644 --- a/scripts/lib/repository-layout.ts +++ b/scripts/lib/repository-layout.ts @@ -32,6 +32,7 @@ export const REPOSITORY_LAYOUT_SETS = Object.freeze([ "feature-typecheck", "product-typecheck", "app-typecheck", + "dependency-cache-key", ] as const); export type RepositoryLayoutSet = (typeof REPOSITORY_LAYOUT_SETS)[number]; diff --git a/scripts/run-in-system-container.sh b/scripts/run-in-system-container.sh index 3fc7aa58..7ba7bfb5 100755 --- a/scripts/run-in-system-container.sh +++ b/scripts/run-in-system-container.sh @@ -25,6 +25,15 @@ node_root=$(dirname "$(dirname "$(command -v node)")") corepack_home=${COREPACK_HOME:-$HOME/.cache/node/corepack} # The environment the gate reads (scripts/verify.sh ci_env, the workflow's global env). pass_env=(CI VITE_BUILD_ID VITE_COMMIT_SHA RELEASE_ID CI_RUNNER_IMAGE SOURCE_DATE_EPOCH APP_PROFILE RELEASE_TARGET) +# A merge job's dependency cache (scripts/contracts/ci-gates.ts DEPENDENCY_CACHE): pnpm's store and metadata +# cache go in at the same paths, so the install in here reuses what the job's install fetched. +pnpm_dirs=() +for name in PNPM_CONFIG_STORE_DIR PNPM_CONFIG_CACHE_DIR; do + if [ -n "${!name:-}" ] && [ -d "${!name}" ]; then + pass_env+=("$name") + pnpm_dirs+=("${!name}") + fi +done say() { echo "system-container: $*" >&2; } fail() { say "$*"; exit 3; } @@ -68,6 +77,10 @@ else fi tar -C "$node_root" -cf - . | $docker exec -i "$cid" sh -c 'mkdir -p /opt/node && tar -C /opt/node --no-same-owner -xf -' \ || fail "copying node failed" +for dir in "${pnpm_dirs[@]}"; do + tar -C "$dir" -cf - . | $docker exec -i "$cid" sh -c "mkdir -p '$dir' && tar -C '$dir' --no-same-owner -xf -" \ + || fail "copying $dir failed" +done if [ -d "$corepack_home" ]; then tar -C "$corepack_home" -cf - . | $docker exec -i "$cid" sh -c 'mkdir -p /opt/corepack && tar -C /opt/corepack --no-same-owner -xf -' \ || fail "copying the corepack cache failed" diff --git a/src/presentation/adapters/query/application-query.ts b/src/presentation/adapters/query/application-query.ts index 943488e8..99296c9c 100644 --- a/src/presentation/adapters/query/application-query.ts +++ b/src/presentation/adapters/query/application-query.ts @@ -282,6 +282,13 @@ type ApplicationMutationController = Readonly<{ * `state.unknownEffectResendable` carries the same answer to `AsyncSurface`. */ canResendUnknownEffect: boolean; + /** + * 1112/01-01. Whether the oldest request is unknown now, read at the + * call, not from the last render: a form asks it when a resend has ended + * (`useAppForm` `mutation`). `state.indicator` says the same once the + * hook renders again. + */ + holdsUnknownEffect(): boolean; }>; type MutationExecution = @@ -878,6 +885,11 @@ export function useApplicationMutation( return submit(head.input as Input); }, [submit, unknownEffectChannel]); + const holdsUnknownEffect = useCallback( + () => unknownEffectChannel?.admissions[0]?.state === "UNKNOWN", + [unknownEffectChannel], + ); + const unknownEffectHead = unknownEffectChannel?.admissions[0]; const canResendUnknownEffect = unknownEffectChannel !== null && @@ -900,6 +912,7 @@ export function useApplicationMutation( reconcileUnknownEffect, resendUnknownEffect, canResendUnknownEffect, + holdsUnknownEffect, }); } diff --git a/src/presentation/components/async-surface.tsx b/src/presentation/components/async-surface.tsx index 041d3072..f2773888 100644 --- a/src/presentation/components/async-surface.tsx +++ b/src/presentation/components/async-surface.tsx @@ -142,6 +142,12 @@ export type AsyncSurfaceProps = Readonly<{ * terminal error shows its own `failure.requestId`. */ supportReference?: string | undefined; + /** + * 1112/04-02. Words about the unknown save shown with it (a resend the + * server refused before the write: `form.resendLater`), not under the input + * error summary. + */ + notice?: ReactNode; }>; export function AsyncSurface({ @@ -155,6 +161,7 @@ export function AsyncSurface({ onResendUnknownEffect, headingLevel, supportReference, + notice, }: AsyncSurfaceProps) { const { message } = useLocale(); if (state.base === "idle") return idle ?? null; @@ -231,6 +238,7 @@ export function AsyncSurface({ {message("action.resendMutation")} ) : null} + {state.indicator === "mutation-effect-unknown" && notice ?

{notice}

: null} {state.indicator === "mutation-effect-unknown" && supportReference ? (

{message("template.supportReference", { diff --git a/src/presentation/design-system/index.ts b/src/presentation/design-system/index.ts index 4ec1456e..535d724f 100644 --- a/src/presentation/design-system/index.ts +++ b/src/presentation/design-system/index.ts @@ -123,6 +123,7 @@ export { FormActions, FormFailureStatus, FormField, + FormSaveFeedback, useAppForm, useDirtyNavigationGuard, } from "../forms/index.ts"; diff --git a/src/presentation/design-system/primitives/checkbox.tsx b/src/presentation/design-system/primitives/checkbox.tsx index bfce9843..b132724b 100644 --- a/src/presentation/design-system/primitives/checkbox.tsx +++ b/src/presentation/design-system/primitives/checkbox.tsx @@ -42,7 +42,11 @@ export const Checkbox = forwardRef( }} type="checkbox" /> - {label} + + {label} + {/* 1112/05-13. The symbol as Field draws it; the state is on the input. */} + {props.required ? : null} + {description ? (

diff --git a/src/presentation/design-system/primitives/dialog.tsx b/src/presentation/design-system/primitives/dialog.tsx index fcb0ea3b..8e1563d2 100644 --- a/src/presentation/design-system/primitives/dialog.tsx +++ b/src/presentation/design-system/primitives/dialog.tsx @@ -41,6 +41,7 @@ export const Dialog = forwardRef( const dialogRef = useRef(null); const previousFocusRef = useRef(null); const focusRestoreGenerationRef = useRef(0); + const innerEscapeRef = useRef(false); const titleId = useId(); const descriptionId = useId(); useImperativeHandle(forwardedRef, () => dialogRef.current!, []); @@ -103,16 +104,26 @@ export const Dialog = forwardRef( className={`ui-dialog ${className}`.trim()} onCancel={(event) => { event.preventDefault(); + // The Escape that fired this cancel closed an inner layer. + if (innerEscapeRef.current) return; onClose(); }} onClick={(event) => { if (event.target === event.currentTarget) onClose(); }} onKeyDown={(event) => { - if (event.key === "Escape") { - event.preventDefault(); - onClose(); + if (event.key !== "Escape") return; + // 1112/05-11. A Menu, Popover or Tooltip inside handled this Escape + // (it prevented the default): it closes that layer, not the Dialog. + if (event.defaultPrevented) { + innerEscapeRef.current = true; + globalThis.setTimeout(() => { + innerEscapeRef.current = false; + }, 0); + return; } + event.preventDefault(); + onClose(); }} ref={dialogRef} > diff --git a/src/presentation/design-system/primitives/escape-layer.ts b/src/presentation/design-system/primitives/escape-layer.ts new file mode 100644 index 00000000..ada44548 --- /dev/null +++ b/src/presentation/design-system/primitives/escape-layer.ts @@ -0,0 +1,15 @@ +/** + * 1112/05-11. Whether an Escape is for a layer drawn over the page (a + * Popover or a shown Tooltip) whose root is `root`. Not when it was pressed + * inside a dialog that does not hold the layer: that Escape is the dialog's. + * An Escape from the layer, from a dialog around it, or from no element + * (focus on the body, as after a click in WebKit) is the layer's. + */ +export function escapeIsForLayer(event: KeyboardEvent, root: Element | null): boolean { + const target = event.target; + if (root === null || !(target instanceof Element) || root.contains(target)) { + return true; + } + const dialog = target.closest("dialog"); + return dialog === null || dialog.contains(root); +} diff --git a/src/presentation/design-system/primitives/popover.tsx b/src/presentation/design-system/primitives/popover.tsx index 98e1438d..6b9e8490 100644 --- a/src/presentation/design-system/primitives/popover.tsx +++ b/src/presentation/design-system/primitives/popover.tsx @@ -1,6 +1,7 @@ import { useEffect, useId, useRef, useState } from "react"; import { Button } from "./button.tsx"; +import { escapeIsForLayer } from "./escape-layer.ts"; export type PopoverProps = Readonly<{ triggerLabel: string; @@ -12,6 +13,7 @@ export function Popover({ triggerLabel, children }: PopoverProps) { const rootRef = useRef(null); const triggerRef = useRef(null); const contentId = useId(); + const triggerId = useId(); useEffect(() => { if (!open) return; @@ -24,17 +26,25 @@ export function Popover({ triggerLabel, children }: PopoverProps) { triggerRef.current?.focus(); } } + // Capture phase, and the default prevented: the Escape closes this + // layer only, not a Dialog around it (1112/05-11). An Escape pressed in + // a Dialog this popover is not in is the Dialog's. function closeOnEscape(event: KeyboardEvent) { - if (event.key === "Escape") { + if ( + event.key === "Escape" && + !event.defaultPrevented && + escapeIsForLayer(event, rootRef.current) + ) { + event.preventDefault(); setOpen(false); triggerRef.current?.focus(); } } document.addEventListener("pointerdown", closeOutside); - document.addEventListener("keydown", closeOnEscape); + document.addEventListener("keydown", closeOnEscape, true); return () => { document.removeEventListener("pointerdown", closeOutside); - document.removeEventListener("keydown", closeOnEscape); + document.removeEventListener("keydown", closeOnEscape, true); }; }, [open]); @@ -43,6 +53,7 @@ export function Popover({ triggerLabel, children }: PopoverProps) { {open ? ( -