From c15345cb1dc7cdd1e3d1b78fe68edaca9f471873 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Thu, 5 Nov 2026 01:33:38 +0900 Subject: [PATCH] =?UTF-8?q?fix(dev):=20dev=20server=EA=B0=80=20=EC=84=A4?= =?UTF-8?q?=EC=B9=98=EB=90=9C=20=EA=B8=B0=EB=8A=A5=EC=9D=98=20contract=20s?= =?UTF-8?q?et=EC=9C=BC=EB=A1=9C=20release=20manifest=EB=A5=BC=20=EB=82=B8?= =?UTF-8?q?=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제 `create:feature`가 만든 기능은 계약 패키지(`@org-contracts/`)를 선언한다. dev server는 커밋된 자리표시자 public/release-manifest.json을 그대로 내주는데, 그 contractSet.packages는 고정된 빈 목록이다. 부팅이 이 집합을 설치된 선언과 대조하므로, 기능을 생성한 직후 `corepack pnpm dev`가 CONTRACT_SET_PACKAGE_MISSING으로 "애플리케이션을 시작할 수 없습니다"를 보인다. 같은 이유로 dev server를 쓰는 FE-GATE-008의 test:browser-capabilities가 38건 실패하고("Execution context was destroyed"), 매뉴얼에는 이 파일을 고치라는 말이 없다. 매뉴얼만으로 기능을 더하는 재실험(리뷰 조치 X2 #3)에서 찾았다. 고른 방법 - dev 전용 Vite 플러그인(scripts/lib/dev-release-manifest.ts)이 dev server를 시작할 때 scripts/write-dev-release-manifest.ts를 자식 프로세스로 돌려 src/.generated/dev-release-manifest.json(무시되는 생성물)을 쓰고, `/release-manifest.json` 요청에 그것을 낸다. 내용은 자리표시자에 설치된 기능의 contract set(build와 같은 buildContractSet)을 넣은 것이다. - 자식 프로세스로 돌리는 이유: contract set을 만들려면 설치된 기능 선언을 import해야 하는데, Vite 설정이 그것을 불러오면 안 된다. - build는 바뀌지 않는다. 빌드 manifest는 generate-build-manifest.ts가 만든다. - 버린 대안: dev 자리표시자에서 contractSet을 빼기. V2 manifest 스키마가 contractSet을 요구한다. 생성기가 추적 파일(public/release-manifest.json)을 다시 쓰기: 기능 선택이 바뀌는 실행마다 추적 파일이 바뀐다. 위험·한계 - dev server를 켠 뒤 기능을 더하거나 지우면 dev server를 다시 켜야 한다. - 자리표시자의 routeChunks는 여전히 손으로 둔다(부팅이 dev에서 보지 않는다). 검증 - tests/unit/dev-release-manifest.test.ts 2건(낡은 집합을 설치된 집합으로 바꾼다, 템플릿 그대로면 자리표시자와 같다). - check:types, lint, check:architecture, check:ci 통과. - 생성 기능을 더한 깨끗한 clone의 capability 실행은 X4 재실행에서 본다. Refs: docs/reviews/2026-11-03-maturity-review/README.md 14.6 X2 #3 --- scripts/lib/dev-release-manifest.ts | 42 +++++++++++++++++++ scripts/write-dev-release-manifest.ts | 27 ++++++++++++ tests/unit/dev-release-manifest.test.ts | 56 +++++++++++++++++++++++++ vite.config.ts | 3 +- 4 files changed, 127 insertions(+), 1 deletion(-) create mode 100644 scripts/lib/dev-release-manifest.ts create mode 100644 scripts/write-dev-release-manifest.ts create mode 100644 tests/unit/dev-release-manifest.test.ts diff --git a/scripts/lib/dev-release-manifest.ts b/scripts/lib/dev-release-manifest.ts new file mode 100644 index 00000000..4b718ab5 --- /dev/null +++ b/scripts/lib/dev-release-manifest.ts @@ -0,0 +1,42 @@ +import { execFileSync } from "node:child_process"; +import { readFileSync } from "node:fs"; +import path from "node:path"; + +import type { Plugin } from "vite"; + +/** Generated at dev server start; ignored with the rest of src/.generated/. */ +export const DEV_RELEASE_MANIFEST_PATH = "src/.generated/dev-release-manifest.json"; + +/** + * Serve only. The dev server answers the runtime's release-manifest request + * with scripts/write-dev-release-manifest.ts's output instead of the committed + * placeholder, so a feature that `create:feature` just added boots in + * `corepack pnpm dev` and in the dev-server browser tests. The manifest is + * written in a child process because it imports the installed feature + * declarations, which this config must not load. A build never uses it: the + * built manifest comes from scripts/generate-build-manifest.ts. + */ +export function devReleaseManifestPlugin(repositoryRoot = process.cwd()): Plugin { + return { + name: "frontend-dev-release-manifest", + apply: "serve", + configureServer(server) { + execFileSync( + process.execPath, + [path.join(repositoryRoot, "scripts/write-dev-release-manifest.ts")], + { cwd: repositoryRoot, stdio: "inherit" }, + ); + const manifest = path.join(repositoryRoot, DEV_RELEASE_MANIFEST_PATH); + server.middlewares.use((request, response, next) => { + const pathname = new URL(request.url ?? "/", "http://dev.invalid").pathname; + if (request.method !== "GET" || !pathname.endsWith("/release-manifest.json")) { + next(); + return; + } + response.setHeader("content-type", "application/json"); + response.setHeader("cache-control", "no-store"); + response.end(readFileSync(manifest)); + }); + }, + }; +} diff --git a/scripts/write-dev-release-manifest.ts b/scripts/write-dev-release-manifest.ts new file mode 100644 index 00000000..bd194eb4 --- /dev/null +++ b/scripts/write-dev-release-manifest.ts @@ -0,0 +1,27 @@ +import { mkdir, readFile, writeFile } from "node:fs/promises"; +import { dirname } from "node:path"; + +import { buildContractSet } from "./generate-contract-set.ts"; +import { DEV_RELEASE_MANIFEST_PATH } from "./lib/dev-release-manifest.ts"; + +/** + * The release manifest the dev server serves: the committed placeholder + * (public/release-manifest.json) with the contract set of the features + * installed now. Boot checks that set against the installed declarations, so + * a placeholder with a fixed set refused every app with one more feature + * (CONTRACT_SET_PACKAGE_MISSING) until someone edited it by hand. The output + * is generated and ignored, as src/.generated/ is. + */ +export async function writeDevReleaseManifest( + source = "public/release-manifest.json", + output = DEV_RELEASE_MANIFEST_PATH, +): Promise { + const manifest = JSON.parse(await readFile(source, "utf8")) as Record; + manifest["contractSet"] = buildContractSet(); + await mkdir(dirname(output), { recursive: true }); + await writeFile(output, `${JSON.stringify(manifest, null, 2)}\n`, "utf8"); +} + +if (process.argv[1]?.endsWith("write-dev-release-manifest.ts")) { + await writeDevReleaseManifest(); +} diff --git a/tests/unit/dev-release-manifest.test.ts b/tests/unit/dev-release-manifest.test.ts new file mode 100644 index 00000000..061abbff --- /dev/null +++ b/tests/unit/dev-release-manifest.test.ts @@ -0,0 +1,56 @@ +import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises"; +import { tmpdir } from "node:os"; +import path from "node:path"; + +import { afterEach, describe, expect, it } from "vitest"; + +import { buildContractSet } from "../../scripts/generate-contract-set.ts"; +import { writeDevReleaseManifest } from "../../scripts/write-dev-release-manifest.ts"; + +/** + * 1103 X2. `create:feature` declares a contract package; the dev server used + * to serve the committed placeholder with a fixed empty set, so the app it + * had just generated refused to boot in `corepack pnpm dev`. + */ +describe("dev release manifest", () => { + let directory: string | undefined; + afterEach(async () => { + if (directory) await rm(directory, { recursive: true, force: true }); + directory = undefined; + }); + + it("serves the placeholder with the contract set of the installed features", async () => { + directory = await mkdtemp(path.join(tmpdir(), "dev-release-manifest-")); + const source = path.join(directory, "release-manifest.json"); + const output = path.join(directory, "generated", "dev-release-manifest.json"); + await writeFile( + source, + JSON.stringify({ + schemaVersion: 2, + buildId: "local-build", + contractSet: { + setAlgorithm: "CA_CONTRACT_SET_V1", + setDigest: "sha256:stale", + packages: [{ packageId: "@org-contracts/removed" }], + }, + }), + ); + + await writeDevReleaseManifest(source, output); + + const written = JSON.parse(await readFile(output, "utf8")) as Record; + expect(written["buildId"]).toBe("local-build"); + expect(written["contractSet"]).toEqual(JSON.parse(JSON.stringify(buildContractSet()))); + }); + + it("matches the committed placeholder while the template's own features are installed", async () => { + directory = await mkdtemp(path.join(tmpdir(), "dev-release-manifest-")); + const output = path.join(directory, "dev-release-manifest.json"); + + await writeDevReleaseManifest("public/release-manifest.json", output); + + expect(JSON.parse(await readFile(output, "utf8"))).toEqual( + JSON.parse(await readFile("public/release-manifest.json", "utf8")), + ); + }); +}); diff --git a/vite.config.ts b/vite.config.ts index 60053a34..9ae07aee 100644 --- a/vite.config.ts +++ b/vite.config.ts @@ -6,6 +6,7 @@ import { defineConfig, loadEnv } from "vite"; import react from "@vitejs/plugin-react"; import tailwindcss from "@tailwindcss/vite"; +import { devReleaseManifestPlugin } from "./scripts/lib/dev-release-manifest.ts"; import { viteModuleInventoryPlugin } from "./scripts/lib/vite-module-inventory.ts"; import { ENV_REGISTRY } from "./src/contracts/env.ts"; @@ -175,7 +176,7 @@ export default defineConfig(({ command, mode }) => { assertRuntimeConfigUnderBase(process.env, base); return { base, - plugins: [react(), tailwindcss(), viteModuleInventoryPlugin()], + plugins: [react(), tailwindcss(), viteModuleInventoryPlugin(), devReleaseManifestPlugin()], // Development keeps the router's warnings. resolve: command === "build" ? { alias: reactRouterProductionAliases(process.cwd()) } : {}, build: {