feat: vendor the public read contract, and give it its own source switch

The public surface — 17 of the 28 registered routes — reads from a 29KB TypeScript fixture and never touches the backend. `TECH_LOG_STUDIO_SOURCE` only ever switched the Studio gateways; `publicContent` was wired to the static adapter unconditionally, so no configuration could make the public site show published content. This is the first half of closing that: the contract and the switch, with the adapter still to come. The generator now vendors both canonical contracts instead of one. They are independent — different services on different schedules — so each carries its own digest and operation list, and updating one leaves the other's drift gate quiet. `TECH_LOG_PUBLIC_SOURCE` is deliberately a second flag rather than a rename of the Studio one. The combination that matters right now is exactly the one a single flag cannot express: the authoring backend is live while the public read API does not exist yet. production stays on MOCK for that reason — pointing it at HTTP today would empty the live site — and moves when the backend serves /api/v1/public. Also records the compatibility evidence the registry gate wanted for the Studio access change in fff5e6f. That gate has been failing since, which is on me: the change was real and breaking, and it shipped without the note explaining that route ids and schemas are untouched and only the access classification moves.
2026-08-20 16:19:53 +09:00
parent 83409bef7a
commit c362ec6100
17 changed files with 3931 additions and 63 deletions
@@ -1,5 +1,5 @@
 /**
- * canonical studio-v1.yaml을 vendor하고 타입을 생성한다.
+ * canonical 계약(studio-v1, public-v1)을 vendor하고 타입을 생성한다.
 *
 * 생성기는 저장소 의존성에 넣지 않는다. `openapi-typescript`는 TypeScript 5의
 * classic compiler API를 요구하는데 이 저장소는 TypeScript 7.0.2를 고정하고
@@ -12,15 +12,45 @@
 */
 import { createHash } from "node:crypto";
 import { execFileSync } from "node:child_process";
-import { readFileSync, writeFileSync } from "node:fs";
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
 import { argv, env, exit } from "node:process";

 const CANONICAL_ROOT =
  env.TECH_LOG_DESIGN_PACKAGE ?? "/home/donghyeon/workspace/tech-log-design-package";
-const CANONICAL_YAML = `${CANONICAL_ROOT}/contracts/openapi/studio-v1.yaml`;
-const VENDOR_YAML = "src/features/tech-log/contracts/studio/studio-api.openapi.yaml";
-const GENERATED = "src/features/tech-log/contracts/studio/generated.ts";
-const SOURCE_RECORD = "src/features/tech-log/contracts/studio/canonical-source.json";
+
+/**
+ * 계약은 둘이고 서로 독립이다. Studio는 인증된 작성 표면이고, Public은 인증
+ * 없는 조회 표면이다. 각자 자기 canonical yaml에서 나오고 자기 digest를 들고
+ * 다니므로, 한쪽이 갱신돼도 다른 쪽 drift 게이트는 조용하다.
+ */
+type ContractTarget = Readonly<{
+  name: string;
+  packageId: string;
+  canonicalYaml: string;
+  vendorYaml: string;
+  generated: string;
+  sourceRecord: string;
+}>;
+
+const CONTRACTS: readonly ContractTarget[] = Object.freeze([
+  Object.freeze({
+    name: "studio",
+    packageId: "@tech-log/studio-contract",
+    canonicalYaml: `${CANONICAL_ROOT}/contracts/openapi/studio-v1.yaml`,
+    vendorYaml: "src/features/tech-log/contracts/studio/studio-api.openapi.yaml",
+    generated: "src/features/tech-log/contracts/studio/generated.ts",
+    sourceRecord: "src/features/tech-log/contracts/studio/canonical-source.json",
+  }),
+  Object.freeze({
+    name: "public",
+    packageId: "@tech-log/public-contract",
+    canonicalYaml: `${CANONICAL_ROOT}/contracts/openapi/public-v1.yaml`,
+    vendorYaml: "src/features/tech-log/contracts/public/public-api.openapi.yaml",
+    generated: "src/features/tech-log/contracts/public/generated.ts",
+    sourceRecord: "src/features/tech-log/contracts/public/canonical-source.json",
+  }),
+]);

 const OPENAPI_TYPESCRIPT = "openapi-typescript@7.9.1";
 const GENERATOR_TYPESCRIPT = "typescript@5.9.3";
@@ -56,71 +86,84 @@ function fail(problems: readonly string[]): never {
 }

 if (check) {
-  const vendored = readFileSync(VENDOR_YAML, "utf8");
-  const generated = readFileSync(GENERATED, "utf8");
-  const record = JSON.parse(readFileSync(SOURCE_RECORD, "utf8")) as CanonicalRecord;
  const problems: string[] = [];
+  const summaries: string[] = [];

-  if (digestOf(readFileSync(VENDOR_YAML)) !== record.digest) {
-    problems.push(`${VENDOR_YAML} does not hash to the recorded digest`);
-  }
-  const vendoredOperations = operationIdsOf(vendored);
-  if (vendoredOperations.join(" ") !== [...record.operationIds].join(" ")) {
-    problems.push(`${SOURCE_RECORD} operationIds differ from ${VENDOR_YAML}`);
-  }
-  if (specVersionOf(vendored) !== record.version) {
-    problems.push(`${SOURCE_RECORD} version differs from ${VENDOR_YAML}`);
-  }
-  // 생성물은 operationId로 키가 매겨진 `operations` 인터페이스를 노출한다.
-  for (const operationId of record.operationIds) {
-    if (!new RegExp(`^\\s{4}${operationId}:`, "mu").test(generated)) {
-      problems.push(`${GENERATED} is missing operation ${operationId}`);
+  for (const target of CONTRACTS) {
+    const vendored = readFileSync(target.vendorYaml, "utf8");
+    const generated = readFileSync(target.generated, "utf8");
+    const record = JSON.parse(readFileSync(target.sourceRecord, "utf8")) as CanonicalRecord;
+
+    if (digestOf(readFileSync(target.vendorYaml)) !== record.digest) {
+      problems.push(`${target.vendorYaml} does not hash to the recorded digest`);
    }
+    if (operationIdsOf(vendored).join(" ") !== [...record.operationIds].join(" ")) {
+      problems.push(`${target.sourceRecord} operationIds differ from ${target.vendorYaml}`);
+    }
+    if (specVersionOf(vendored) !== record.version) {
+      problems.push(`${target.sourceRecord} version differs from ${target.vendorYaml}`);
+    }
+    if (record.packageId !== target.packageId) {
+      problems.push(`${target.sourceRecord} packageId is not ${target.packageId}`);
+    }
+    // 생성물은 operationId로 키가 매겨진 `operations` 인터페이스를 노출한다.
+    for (const operationId of record.operationIds) {
+      if (!new RegExp(`^\\s{4}${operationId}:`, "mu").test(generated)) {
+        problems.push(`${target.generated} is missing operation ${operationId}`);
+      }
+    }
+    summaries.push(
+      `${record.packageId}@${record.version} (${record.sourceRevision}), ${record.operationIds.length} operations`,
+    );
  }
+
  if (problems.length > 0) fail(problems);
-  console.log(
-    `tech-log contract is in sync: ${record.packageId}@${record.version} (${record.sourceRevision}), ${record.operationIds.length} operations.`,
-  );
+  console.log(`tech-log contracts are in sync:\n- ${summaries.join("\n- ")}`);
  exit(0);
 }

-const canonicalBytes = readFileSync(CANONICAL_YAML);
-const canonicalText = canonicalBytes.toString("utf8");
+const sourceRevision = execFileSync(
+  "git",
+  ["-C", CANONICAL_ROOT, "rev-parse", "--short=7", "HEAD"],
+  { encoding: "utf8" },
+).trim();

-const record: CanonicalRecord = {
-  packageId: "@tech-log/studio-contract",
-  version: specVersionOf(canonicalText),
-  digest: digestOf(canonicalBytes),
-  sourceRevision: execFileSync(
-    "git",
-    ["-C", CANONICAL_ROOT, "rev-parse", "--short=7", "HEAD"],
-    { encoding: "utf8" },
-  ).trim(),
-  operationIds: operationIdsOf(canonicalText),
-};
+for (const target of CONTRACTS) {
+  const canonicalBytes = readFileSync(target.canonicalYaml);
+  const canonicalText = canonicalBytes.toString("utf8");

-// 격리 실행. 저장소의 node_modules와 lockfile은 그대로다.
-const generated = execFileSync(
-  "corepack",
-  [
-    "pnpm",
-    "dlx",
-    "--package",
-    GENERATOR_TYPESCRIPT,
-    "--package",
-    OPENAPI_TYPESCRIPT,
-    "openapi-typescript",
-    CANONICAL_YAML,
-  ],
-  { encoding: "utf8", maxBuffer: 32 * 1024 * 1024 },
-);
+  const record: CanonicalRecord = {
+    packageId: target.packageId,
+    version: specVersionOf(canonicalText),
+    digest: digestOf(canonicalBytes),
+    sourceRevision,
+    operationIds: operationIdsOf(canonicalText),
+  };

-writeFileSync(VENDOR_YAML, canonicalText);
-writeFileSync(GENERATED, generated);
-writeFileSync(SOURCE_RECORD, `${JSON.stringify(record, null, 2)}\n`);
-console.log(
-  `Generated from ${record.packageId}@${record.version} (${record.sourceRevision}), ${record.operationIds.length} operations.`,
-);
+  // 격리 실행. 저장소의 node_modules와 lockfile은 그대로다.
+  const generated = execFileSync(
+    "corepack",
+    [
+      "pnpm",
+      "dlx",
+      "--package",
+      GENERATOR_TYPESCRIPT,
+      "--package",
+      OPENAPI_TYPESCRIPT,
+      "openapi-typescript",
+      target.canonicalYaml,
+    ],
+    { encoding: "utf8", maxBuffer: 32 * 1024 * 1024 },
+  );
+
+  mkdirSync(dirname(target.vendorYaml), { recursive: true });
+  writeFileSync(target.vendorYaml, canonicalText);
+  writeFileSync(target.generated, generated);
+  writeFileSync(target.sourceRecord, `${JSON.stringify(record, null, 2)}\n`);
+  console.log(
+    `Generated from ${record.packageId}@${record.version} (${record.sourceRevision}), ${record.operationIds.length} operations.`,
+  );
+}

 // 재생성은 매번 package digest를 바꾼다. `pnpm dev`가 그대로 서빙하는
 // `public/release-manifest.json`은 build가 컴파일한 contract set을 그대로