@sayren/store-sdk 0.18.0 → 0.20.0

package/src/schemas/storefront-hosting.ts

@@ -0,0 +1,841 @@
+import { z } from "zod";
+import { RESERVED_STORE_CODES } from "./store";
+
+/**
+ * 스토어프론트 호스팅 (이슈 #53, M1: 템플릿 발행) — 관리 API `/v1/storefront/**`의 계약이다.
+ *
+ * 셀러는 템플릿을 골라 사이트를 만들고 `{slug}.{호스팅 도메인}` 주소를 받는다. 발행은 버전 단위이고,
+ * 되돌리기는 이전 버전을 다시 발행하는 것이다(재빌드 없음). 상태의 원천은 api DB이고 Cloudflare 쪽 반영
+ * (라우팅 표·사이트 Worker)은 커밋 뒤 비동기다 — 반영 상태는 `provisioning`으로 본다.
+ *
+ * 스코프는 조회 `storefront:r`, 쓰기 `storefront:rw`(역할 OWNER·ADMIN)다. 에이전트(MCP)의 발행·되돌리기·템플릿 변경·
+ * 공개 전환·슬러그 변경·호스팅 끄기는 승인(`APPROVAL_REQUIRED`)이다 — 구매자가 보는 화면을 바꾸는 쓰기다.
+ *
+ * 오류 코드:
+ * - 403 `STOREFRONT_HOSTING_DISABLED` — 플랫폼 스위치가 꺼져 새 사이트를 만들 수 없다
+ * - 404 `STOREFRONT_SITE_NOT_FOUND` · `STOREFRONT_TEMPLATE_NOT_FOUND` · `STOREFRONT_VERSION_NOT_FOUND`
+ * - 409 `STOREFRONT_SITE_EXISTS` — 이미 사이트가 있다(스토어당 1개)
+ * - 409 `STOREFRONT_SLUG_TAKEN` — 다른 사이트가 쓰거나 보류 중인 슬러그다
+ * - 409 `STOREFRONT_SLUG_CHANGE_LIMIT` — 슬러그는 스토어당 30일에 3번까지 바꾼다
+ * - 409 `STOREFRONT_SITE_CREATE_LIMIT` — 사이트는 스토어당 30일에 3번까지 만든다
+ * - 409 `STOREFRONT_SITE_CHANGED` — 읽은 상태(`expected*`)와 현재 상태가 다르다. 다시 읽고 시도한다
+ * - 409 `STOREFRONT_SITE_NOT_ACTIVE` — 정지(`SUSPENDED`)된 사이트는 바꾸거나 끌 수 없다
+ * - 409 `STOREFRONT_VERSION_NOT_READY` — 빌드가 끝나지 않았거나 실패한 버전은 발행할 수 없다
+ * - 409 `STOREFRONT_NO_ROLLBACK_TARGET` — 되돌릴 이전 발행 버전이 없다
+ * - 400 `STOREFRONT_SLUG_CONFIRM_MISMATCH` — 호스팅 끄기 확인 입력이 현재 슬러그와 다르다
+ * - 503 `STOREFRONT_PREVIEW_NOT_CONFIGURED` — 미리보기 서명 키가 설정되지 않았다
+ *
+ * 편집(M2b, `/v1/storefront/site/editing`·`files/**`·`checks/**`·`verify`·`builds/**`, 버전 만들기):
+ * - 403 `STOREFRONT_EDITING_DISABLED` — 플랫폼 편집 스위치가 꺼져 있다
+ * - 503 `STOREFRONT_EDITING_NOT_CONFIGURED` — 편집 Sandbox가 설정되지 않았다
+ * - 409 `EDIT_CAPACITY_FULL` — 플랫폼 전체 동시 편집 상한에 걸렸다. `error.details.retryAfterSeconds` 뒤에 다시 한다
+ * - 409 `EDIT_SESSION_REQUIRED` — 편집 미리보기 링크: 편집 환경이 없다
+ * - 409 `CHECK_RUNNING` — 이 사이트에서 다른 종류의 검사가 돌고 있다(`error.details.checkId`)
+ * - 404 `STOREFRONT_CHECK_NOT_FOUND`
+ * - 409 `FILE_CHANGED` — 해시 조건이 어긋났다. 아무것도 쓰지 않았다(`error.details.conflicts: [{ path, currentHash }]`)
+ * - 409 `FILE_EXISTS` — 옮길 자리에 파일이 있다(`overwrite: true`로 덮는다)
+ * - 404 `FILE_NOT_FOUND` — 파일이 없다
+ * - 400 `INVALID_FILE_PATH` — 경로 형식이 틀렸거나 편집할 수 없는 경로다(`node_modules`·`dist`·`.env*` 등). 쓸 수 있는 곳은
+ *   `src/**`·`public/**`와 루트 설정 파일 몇 개이고, `package.json`·`pnpm-lock.yaml`은 읽기만 된다
+ * - 413 `FILE_TOO_LARGE`·`WORKSPACE_TOO_LARGE` — 파일 하나 1MiB, 작업 트리 전체 20MiB·2,000개를 넘는다
+ * - 409 `STOREFRONT_BUILD_IN_PROGRESS` — 이 사이트에 끝나지 않은 빌드가 있다(사이트당 하나)
+ * - 404 `STOREFRONT_BUILD_NOT_FOUND`
+ * - 502 `STOREFRONT_SANDBOX_UNAVAILABLE` — 편집 Sandbox 호출이 실패했다. 잠시 뒤 다시 한다
+ */
+
+// ─── 슬러그 ───────────────────────────────────────────────
+
+/**
+ * 슬러그 형식 — 스토어 코드와 같은 DNS 라벨 규칙(소문자·숫자·하이픈 3~30자, 하이픈으로 시작·끝 불가)에
+ * 연속 하이픈 금지를 더한다. `--`는 버전 미리보기 주소(`v3--{slug}`)와 punycode(`xn--`)가 쓰는 구분자다.
+ */
+export const STOREFRONT_SLUG_PATTERN = /^[a-z0-9](?:[a-z0-9-]{1,28}[a-z0-9])$/;
+
+/** 호스팅 도메인에서 플랫폼이 쓰거나 쓸 이름 — 스토어 코드 예약어에 호스팅 전용 이름을 더한다 */
+export const RESERVED_STOREFRONT_SLUGS: readonly string[] = [
+  ...RESERVED_STORE_CODES,
+  "mcp",
+  "preview",
+  "previews",
+  "sayren",
+  "shop",
+  "shops",
+  "abuse",
+  "security",
+  "closed",
+  "coming-soon",
+  "suspended",
+  "dispatch",
+  "control",
+  "outbound",
+];
+
+/**
+ * 편집 미리보기 호스트 접미사 — 편집 미리보기 주소는 `{사이트 id 정규화}-preview.{호스팅 도메인}`이다(M2b). 사이트 주소와 같은
+ * 1단계 이름이라 슬러그가 이 모양이면 남의 편집 미리보기 주소와 겹칠 수 있어 슬러그로 쓰지 못한다.
+ */
+export const STOREFRONT_EDIT_PREVIEW_SUFFIX = "-preview";
+
+export function isReservedStorefrontSlug(slug: string): boolean {
+  const lower = slug.toLowerCase();
+  return (
+    RESERVED_STOREFRONT_SLUGS.includes(lower) || lower.endsWith(STOREFRONT_EDIT_PREVIEW_SUFFIX)
+  );
+}
+
+/**
+ * 편집 미리보기 호스트 이름의 라벨 — 사이트 id의 `_`를 `-`로 바꾸고 `-preview`를 붙인다(`sfs_ab12cd34` → `sfs-ab12cd34-preview`).
+ * 편집 Sandbox Worker(`apps/hosting-sandbox/src/preview-host.ts`)가 같은 규칙의 복제본을 들고 있고 api
+ * `test/storefront-hosting-parity.spec.ts`가 둘을 대조한다. 규칙을 바꾸면 두 곳을 같이 고친다.
+ */
+export function storefrontEditPreviewLabelOf(siteId: string): string {
+  return `${siteId.replaceAll("_", "-")}${STOREFRONT_EDIT_PREVIEW_SUFFIX}`;
+}
+
+export const storefrontSlugSchema = z
+  .string()
+  .regex(
+    STOREFRONT_SLUG_PATTERN,
+    "소문자·숫자·하이픈 3~30자여야 하고 하이픈으로 시작하거나 끝날 수 없습니다",
+  )
+  .refine((slug) => !slug.includes("--"), "하이픈을 연달아 쓸 수 없습니다")
+  .refine((slug) => !isReservedStorefrontSlug(slug), "플랫폼이 쓰는 이름이라 쓸 수 없습니다")
+  .describe("주소 슬러그. `{slug}.{호스팅 도메인}`이 사이트 주소가 된다");
+
+/** 바꾼 슬러그를 다른 사이트가 가져가지 못하게 막는 기간(일). 보류 동안 옛 주소는 새 주소로 301한다 */
+export const STOREFRONT_SLUG_HOLD_DAYS = 90;
+/** 슬러그 변경 한도 — 이 기간(일) 안에 */
+export const STOREFRONT_SLUG_CHANGE_WINDOW_DAYS = 30;
+/** 슬러그 변경 한도 — 횟수(스토어 단위. 끄고 다시 만들어도 이어서 센다) */
+export const STOREFRONT_SLUG_CHANGE_LIMIT = 3;
+/** 사이트 만들기 한도 — 같은 창(30일) 안의 횟수(스토어 단위). 끄고 만들기를 되풀이해 이름을 묶어 두지 못하게 한다 */
+export const STOREFRONT_SITE_CREATE_LIMIT = 3;
+
+// ─── 템플릿 ───────────────────────────────────────────────
+
+export const storefrontTemplateSchema = z.object({
+  templateId: z.string().describe("템플릿 id (예: `basic`)"),
+  name: z.string().describe("템플릿 이름"),
+  industry: z.string().describe("업종 (예: `general`·`fashion`·`food`). 목록 필터에 쓴다"),
+  description: z.string().describe("템플릿 설명"),
+  thumbnailUrl: z.string().nullable().describe("썸네일 이미지 주소. 없으면 null"),
+  version: z.string().describe("현재 템플릿 버전. 새 사이트·템플릿 변경은 이 버전으로 만든다"),
+  isDefault: z.boolean().describe("기본 템플릿인가 (스토어 생성 시 자동 생성에 쓴다)"),
+});
+export type StorefrontTemplate = z.infer<typeof storefrontTemplateSchema>;
+
+// ─── 버전 ─────────────────────────────────────────────────
+
+/**
+ * 버전 상태 — 템플릿 버전(`source: TEMPLATE`)은 템플릿 산출물을 그대로 쓰므로 만들 때 곧바로 `READY`다. 편집 버전
+ * (`source: EDIT`, M2b)은 작업 트리 스냅샷을 빌드하는 동안 `BUILDING`이고, 빌드·규칙 검증을 통과하면 `READY`, 실패하면
+ * `FAILED`다(실패 단계·로그 꼬리는 `buildId`의 빌드). 발행할 수 있는 것은 `READY`뿐이다. 발행 여부는 상태가 아니라 사이트의
+ * 발행 포인터가 원천이다(`published`).
+ */
+export const storefrontVersionStatusSchema = z
+  .enum(["BUILDING", "READY", "FAILED"])
+  .describe("`BUILDING` 빌드 중 · `READY` 발행 가능 · `FAILED` 빌드 실패");
+export type StorefrontVersionStatus = z.infer<typeof storefrontVersionStatusSchema>;
+
+export const storefrontVersionSchema = z.object({
+  versionId: z.string(),
+  number: z.number().int().min(1).describe("사이트 안에서 1부터 늘어나는 번호 (v1, v2…)"),
+  templateId: z.string().describe("이 버전의 기준 템플릿"),
+  templateVersion: z.string().describe("이 버전의 기준 템플릿 버전"),
+  status: storefrontVersionStatusSchema,
+  published: z.boolean().describe("지금 발행된 버전인가"),
+  publishedAt: z
+    .string()
+    .nullable()
+    .describe("마지막으로 발행한 시각 (ISO 8601). 발행한 적 없으면 null"),
+  message: z.string().nullable().describe("버전 메모"),
+  source: z
+    .enum(["TEMPLATE", "EDIT"])
+    .describe("`TEMPLATE` 템플릿 산출물 그대로 · `EDIT` 편집 작업 트리를 빌드함"),
+  buildId: z
+    .string()
+    .nullable()
+    .describe("편집 버전의 빌드 (`GET /v1/storefront/site/builds/{buildId}`). 템플릿 버전은 null"),
+  createdByType: z
+    .string()
+    .describe("만든 행위자 유형 (`USER`·`AGENT`·`APP`·`TOKEN`·`SYSTEM`). 늘어날 수 있다"),
+  createdAt: z.string().describe("만든 시각 (ISO 8601)"),
+});
+export type StorefrontVersion = z.infer<typeof storefrontVersionSchema>;
+
+// ─── 사이트 ───────────────────────────────────────────────
+
+export const storefrontSiteStatusSchema = z
+  .enum(["ACTIVE", "SUSPENDED", "CLOSED"])
+  .describe("`ACTIVE` 운영 중 · `SUSPENDED` 운영자 정지 · `CLOSED` 호스팅 끔·스토어 폐쇄");
+export type StorefrontSiteStatus = z.infer<typeof storefrontSiteStatusSchema>;
+
+export const storefrontVisibilitySchema = z
+  .enum(["COMING_SOON", "PUBLIC"])
+  .describe("`COMING_SOON` 오픈 준비 중(방문자에게 준비 중 페이지) · `PUBLIC` 공개");
+export type StorefrontVisibility = z.infer<typeof storefrontVisibilitySchema>;
+
+export const storefrontSourceModeSchema = z
+  .enum(["MANAGED", "CUSTOM"])
+  .describe("`MANAGED` 템플릿 그대로 · `CUSTOM` 한 번이라도 편집함");
+
+export const storefrontDomainSchema = z.object({
+  hostname: z.string().describe("호스트 이름 (예: `mystore.sayren.co`)"),
+  kind: z.enum(["PLATFORM", "CUSTOM"]).describe("`PLATFORM` 슬러그 주소 · `CUSTOM` 내 도메인"),
+  status: z
+    .enum(["ACTIVE", "HELD"])
+    .describe("`ACTIVE` 사용 중 · `HELD` 슬러그를 바꿔 보류 중(새 주소로 301)"),
+  isPrimary: z.boolean().describe("대표 주소인가 (`Store.storefrontUrl`)"),
+  holdUntil: z.string().nullable().describe("보류가 끝나는 시각 (ISO 8601). 보류가 아니면 null"),
+});
+export type StorefrontDomain = z.infer<typeof storefrontDomainSchema>;
+
+/**
+ * 호스팅 반영 상태 — 발행·슬러그·공개 전환은 DB에 먼저 확정되고 Cloudflare 반영은 커밋 뒤에 한다.
+ * `PENDING`이면 반영 중이거나 재시도 대기다(잡이 다시 한다). 반영 뒤에도 라우팅 전파에 최대 1분이 걸린다.
+ */
+export const storefrontProvisioningSchema = z.object({
+  status: z
+    .enum(["SYNCED", "PENDING", "FAILED"])
+    .describe(
+      "`SYNCED` 반영됨 · `PENDING` 반영 대기 · `FAILED` 반영이 여러 번 실패함(자동 재시도는 계속한다)",
+    ),
+  lastErrorCode: z.string().nullable().describe("마지막 반영 실패 코드. 없으면 null"),
+  syncedAt: z.string().nullable().describe("마지막으로 반영한 시각 (ISO 8601)"),
+});
+export type StorefrontProvisioning = z.infer<typeof storefrontProvisioningSchema>;
+
+/**
+ * 편집 미리보기 주소(M2b) — 사이트마다 `{사이트 id 정규화}-preview.{호스팅 도메인}` 호스트 하나다. 호스팅 도메인의 와일드카드
+ * 인증서가 덮으므로 따로 준비할 것이 없다. 이 주소는 편집 미리보기 링크(콘솔 전용)로 받은 쿠키가 있어야 열린다.
+ */
+export const storefrontEditPreviewSchema = z.object({
+  hostname: z
+    .string()
+    .nullable()
+    .describe(
+      "편집 미리보기 호스트 (예: `sfs-ab12cd34-preview.sayren.co`). 편집을 쓸 수 없으면 null",
+    ),
+});
+export type StorefrontEditPreview = z.infer<typeof storefrontEditPreviewSchema>;
+
+export const storefrontSiteSchema = z.object({
+  siteId: z.string(),
+  slug: z.string().describe("주소 슬러그"),
+  hostname: z.string().describe("대표 호스트 이름"),
+  url: z.string().describe("대표 주소 (`https://{hostname}`)"),
+  domains: z.array(storefrontDomainSchema).describe("사용 중·보류 중인 호스트 이름"),
+  templateId: z.string().describe("지금 발행된 버전의 템플릿 (발행 전이면 만든 템플릿)"),
+  sourceMode: storefrontSourceModeSchema,
+  status: storefrontSiteStatusSchema,
+  visibility: storefrontVisibilitySchema,
+  publishedVersion: storefrontVersionSchema.nullable().describe("지금 발행된 버전"),
+  provisioning: storefrontProvisioningSchema,
+  editPreview: storefrontEditPreviewSchema,
+  slugChangesRemaining: z
+    .number()
+    .int()
+    .min(0)
+    .describe(`최근 ${STOREFRONT_SLUG_CHANGE_WINDOW_DAYS}일 기준 남은 슬러그 변경 횟수`),
+  createdAt: z.string(),
+  updatedAt: z.string(),
+});
+export type StorefrontSite = z.infer<typeof storefrontSiteSchema>;
+
+/** `GET /v1/storefront/site` — 스위치 상태와 현재 사이트(없으면 null. 끈 사이트는 싣지 않는다) */
+export const storefrontHostingSchema = z.object({
+  enabled: z.boolean().describe("새 사이트를 만들 수 있는가 (플랫폼 스위치)"),
+  domain: z.string().describe("호스팅 도메인 (예: `sayren.co`). 사이트 주소는 `{slug}.{domain}`"),
+  editingEnabled: z
+    .boolean()
+    .describe("파일 편집·버전 만들기를 쓸 수 있는가 (플랫폼 편집 스위치와 Sandbox 설정)"),
+  site: storefrontSiteSchema.nullable(),
+});
+export type StorefrontHosting = z.infer<typeof storefrontHostingSchema>;
+
+export const storefrontSlugAvailabilitySchema = z.object({
+  slug: z.string(),
+  available: z.boolean(),
+  reason: z
+    .enum(["INVALID", "RESERVED", "TAKEN", "CURRENT"])
+    .nullable()
+    .describe(
+      "쓸 수 없는 이유. `INVALID` 형식 · `RESERVED` 예약어 · `TAKEN` 사용·보류 중 · `CURRENT` 지금 내 슬러그",
+    ),
+});
+export type StorefrontSlugAvailability = z.infer<typeof storefrontSlugAvailabilitySchema>;
+
+// ─── 요청 ─────────────────────────────────────────────────
+
+export const createStorefrontSiteRequestSchema = z.object({
+  templateId: z.string().min(1).max(64).describe("템플릿 id"),
+  slug: storefrontSlugSchema.optional().describe("주소 슬러그. 생략하면 스토어 코드"),
+});
+export type CreateStorefrontSiteRequest = z.infer<typeof createStorefrontSiteRequestSchema>;
+
+export const changeStorefrontTemplateRequestSchema = z.object({
+  templateId: z.string().min(1).max(64).describe("바꿀 템플릿 id"),
+  publish: z
+    .boolean()
+    .optional()
+    .describe("새 버전을 곧바로 발행하는가 (기본 true). false면 버전만 만든다"),
+  message: z.string().max(200).optional().describe("버전 메모"),
+});
+export type ChangeStorefrontTemplateRequest = z.infer<typeof changeStorefrontTemplateRequestSchema>;
+
+/**
+ * 발행·되돌리기 — 발행은 사이트의 발행 포인터를 바꾸는 조건부 쓰기다. `expectedPublishedVersionId`를 주면
+ * 지금 발행 버전이 그 값일 때만 바꾼다(화면을 본 뒤 다른 사람이 바꿨으면 409 `STOREFRONT_SITE_CHANGED`).
+ * 이미 그 버전이 발행돼 있으면 아무것도 바꾸지 않고 200이다(같은 요청의 재실행이 안전하다).
+ */
+export const publishStorefrontVersionRequestSchema = z.object({
+  expectedPublishedVersionId: z
+    .string()
+    .nullable()
+    .optional()
+    .describe("화면에서 본 발행 버전 id (발행 전이었으면 null). 생략하면 확인하지 않는다"),
+});
+export type PublishStorefrontVersionRequest = z.infer<typeof publishStorefrontVersionRequestSchema>;
+
+export const rollbackStorefrontRequestSchema = z.object({
+  versionId: z.string().optional().describe("되돌릴 버전. 생략하면 지금 버전 직전에 발행했던 버전"),
+  expectedPublishedVersionId: z.string().nullable().optional(),
+});
+export type RollbackStorefrontRequest = z.infer<typeof rollbackStorefrontRequestSchema>;
+
+export const changeStorefrontSlugRequestSchema = z.object({
+  slug: storefrontSlugSchema,
+});
+export type ChangeStorefrontSlugRequest = z.infer<typeof changeStorefrontSlugRequestSchema>;
+
+export const setStorefrontVisibilityRequestSchema = z.object({
+  visibility: storefrontVisibilitySchema,
+  expectedVisibility: storefrontVisibilitySchema
+    .optional()
+    .describe("화면에서 본 공개 상태. 주면 지금 값이 같을 때만 바꾼다"),
+});
+export type SetStorefrontVisibilityRequest = z.infer<typeof setStorefrontVisibilityRequestSchema>;
+
+/** 호스팅 끄기 — 사이트를 닫고(`CLOSED`) 슬러그를 보류한다. 확인 입력은 현재 슬러그다 */
+export const disableStorefrontHostingRequestSchema = z.object({
+  confirmSlug: z.string().min(1).describe("확인 입력 — 현재 슬러그"),
+});
+export type DisableStorefrontHostingRequest = z.infer<typeof disableStorefrontHostingRequestSchema>;
+
+export const storefrontSlugAvailabilityQuerySchema = z.object({
+  slug: z.string().describe("확인할 슬러그"),
+});
+
+/**
+ * 오픈 준비 중 미리보기 링크 — 콘솔에서 로그인한 OWNER·ADMIN만 받는다(PAT·에이전트 불가). 링크는 5분 안에 한 번 열면
+ * 그 브라우저에 12시간짜리 미리보기 쿠키가 생기고 오픈 준비 중인 사이트의 실제 화면을 본다. 링크를 남에게 넘기면 그 사람도
+ * 볼 수 있으므로 공유하지 않는다.
+ */
+export const createStorefrontPreviewLinkRequestSchema = z.object({
+  path: z.string().max(512).optional().describe("열 경로 (`/`로 시작). 생략하면 `/`"),
+});
+export type CreateStorefrontPreviewLinkRequest = z.infer<
+  typeof createStorefrontPreviewLinkRequestSchema
+>;
+
+export const storefrontPreviewLinkSchema = z.object({
+  url: z.string().describe("미리보기 링크 — 5분 안에 연다"),
+  expiresAt: z.string().describe("링크 만료 시각 (ISO 8601)"),
+});
+export type StorefrontPreviewLink = z.infer<typeof storefrontPreviewLinkSchema>;
+
+// ─── 편집 (M2b) ───────────────────────────────────────────
+//
+// 셀러(콘솔)와 에이전트(MCP)가 사이트의 작업 트리를 고치고 버전을 만든다. 작업 트리는 사이트당 하나이고 편집 Sandbox
+// (격리된 컨테이너)가 dev 서버로 띄운다. 편집 환경은 플랫폼 전체 동시 상한이 있고 15분 동안 활동이 없으면 잠든다(작업
+// 트리는 보존된다). 버전 만들기는 그 시점의 작업 트리를 고정해 일회용 빌드 환경에서 규칙 검증 → 타입 검사 → 빌드를
+// 하고, 통과하면 발행할 수 있는 `READY` 버전이 된다. 에이전트의 파일 쓰기·검사·버전 만들기는 승인 없이 되고, 발행·
+// 되돌리기·공개 전환은 기존대로 승인이다. 편집 미리보기 링크는 콘솔 OWNER·ADMIN만 받는다(에이전트에게 주지 않는다).
+
+/** 플랫폼 전체 동시 편집 환경 상한 */
+export const STOREFRONT_EDIT_CAPACITY = 20;
+/** 활동이 없으면 편집 환경이 잠드는 시간(분). 작업 트리는 보존된다 */
+export const STOREFRONT_EDIT_IDLE_MINUTES = 15;
+/**
+ * 편집 작업(파일 쓰기·검사·버전 만들기·편집 미리보기 링크 발급)이 없으면 서버가 편집 환경을 닫는 시간(분). 미리보기 탭만 열어 두면
+ * 유휴 잠들기(`STOREFRONT_EDIT_IDLE_MINUTES`)가 걸리지 않으므로 이 한도가 편집 환경을 끝낸다. 작업 트리는 보존된다
+ */
+export const STOREFRONT_EDIT_ACTIVITY_TIMEOUT_MINUTES = 30;
+/** 파일 하나의 최대 크기(바이트) */
+export const STOREFRONT_FILE_MAX_BYTES = 1024 * 1024;
+/** 작업 트리 전체 최대 크기(바이트) — 파일 수는 2,000개까지 */
+export const STOREFRONT_WORKSPACE_MAX_BYTES = 20 * 1024 * 1024;
+/** 일괄 쓰기 한 번의 최대 파일 수 */
+export const STOREFRONT_FILE_BATCH_MAX = 50;
+
+/** 편집할 수 없는 경로 조각 — 설치물·산출물 폴더 */
+export const STOREFRONT_BLOCKED_PATH_SEGMENTS: readonly string[] = [
+  "node_modules",
+  "dist",
+  ".output",
+  ".tanstack",
+  ".wrangler",
+  ".git",
+  ".nitro",
+  ".vinxi",
+];
+
+/** 경로 조각에 쓸 수 있는 문자 — 편집 Sandbox Worker의 경로 규칙(sandbox-api.md §2.1)과 같다. TanStack Router 파일명(`$id.tsx`·`_layout`·`(group)`·`[.]`)이 들어간다 */
+export const STOREFRONT_PATH_SEGMENT_PATTERN = /^[A-Za-z0-9$_.()[\]@+=,-]+$/;
+
+/**
+ * 보이지 않거나 표시 방향을 바꾸는 문자 — 제로폭(U+200B~U+200D, U+FEFF)과 bidi 제어(U+202A~U+202E, U+2066~U+2069). 비슷해 보이는
+ * 경로로 규칙 검사를 피하거나 리뷰어를 속이는 데 쓰인다. 문자 규칙이 이미 막지만 이유를 따로 드러내려고 먼저 본다.
+ */
+const INVISIBLE_OR_BIDI = /[\u200B-\u200D\uFEFF\u202A-\u202E\u2066-\u2069]/;
+
+/** 경로 정규화 — NFC. 비교·저장은 이 값으로 한다(같아 보이는 두 경로가 다른 파일이 되지 않게) */
+export function normalizeStorefrontPath(path: string): string {
+  return path.normalize("NFC");
+}
+
+/**
+ * 작업 트리 상대 경로인가(정규화한 값 기준) — `/`로 구분하고 `/`로 시작하지 않는다. `.`·`..`·빈 조각, 조각 문자 규칙
+ * (`STOREFRONT_PATH_SEGMENT_PATTERN`, 공백·역슬래시·제어·제로폭·bidi 문자 불가) 밖, 설치물·산출물 폴더
+ * (`STOREFRONT_BLOCKED_PATH_SEGMENTS`), `.env`로 시작하는 조각(파일·폴더)은 받지 않는다. 최대 256자·깊이 16.
+ * 어디에 쓸 수 있는지(`src/**`·`public/**`·루트 설정 파일)는 편집 Sandbox가 판정한다(400 `INVALID_FILE_PATH`).
+ * 편집 Sandbox Worker가 같은 규칙의 복제본을 들고 있다(api `test/storefront-hosting-parity.spec.ts`가 대조한다).
+ */
+export function isEditableStorefrontPath(path: string): boolean {
+  if (path.length === 0 || path.length > 256) return false;
+  if (INVISIBLE_OR_BIDI.test(path)) return false;
+  if (path !== normalizeStorefrontPath(path)) return false;
+  if (path.startsWith("/")) return false;
+  const segments = path.split("/");
+  if (segments.length > 16) return false;
+  for (const segment of segments) {
+    if (segment === "" || segment === "." || segment === "..") return false;
+    if (!STOREFRONT_PATH_SEGMENT_PATTERN.test(segment)) return false;
+    if (STOREFRONT_BLOCKED_PATH_SEGMENTS.includes(segment)) return false;
+    // `.env`로 시작하는 조각은 어디에 있든 받지 않는다(폴더 이름 포함, 편집 Sandbox `paths.ts`와 같다)
+    if (segment.startsWith(".env")) return false;
+  }
+  return true;
+}
+
+/** 경로 입력 — NFC로 정규화한 뒤 규칙을 본다 */
+export const storefrontFilePathSchema = z
+  .string()
+  .transform(normalizeStorefrontPath)
+  .refine(isEditableStorefrontPath, "편집할 수 없는 경로입니다")
+  .describe("작업 트리 상대 경로 (예: `src/routes/index.tsx`). NFC로 정규화한다");
+
+/** 파일 해시 — 내용 바이트의 SHA-256 hex(소문자 64자) */
+export const storefrontFileHashSchema = z
+  .string()
+  .regex(/^[0-9a-f]{64}$/, "SHA-256 hex여야 합니다")
+  .describe("내용 바이트의 SHA-256 (소문자 hex)");
+
+export const storefrontFileEncodingSchema = z
+  .enum(["utf8", "base64"])
+  .describe("`utf8` 텍스트 · `base64` 바이너리(이미지 등)");
+
+/**
+ * 편집 환경 상태 — `STARTING`은 컨테이너를 띄우고 작업 트리를 복원해 dev 서버를 올리는 중이다(보통 30초 안, 최대
+ * 90초). `RUNNING`이면 미리보기와 파일 쓰기가 바로 반영된다(HMR).
+ */
+export const storefrontEditSessionStatusSchema = z
+  .enum(["STARTING", "RUNNING"])
+  .describe("`STARTING` 띄우는 중 · `RUNNING` 사용 중");
+
+/** 편집 환경을 띄우는 단계 — 콘솔 진행 표시용이다. 값은 늘어날 수 있다 */
+export const STOREFRONT_EDIT_START_STAGES = ["CONTAINER", "RESTORE", "DEV_SERVER"] as const;
+
+export const storefrontEditSessionSchema = z.object({
+  sessionId: z.string(),
+  status: storefrontEditSessionStatusSchema,
+  startStage: z
+    .string()
+    .nullable()
+    .describe(
+      "`STARTING`일 때 지금 단계 (`CONTAINER` 컨테이너 기동 · `RESTORE` 작업 트리 복원 · `DEV_SERVER` 개발 서버 기동). 늘어날 수 있다. `RUNNING`이면 null",
+    ),
+  startedAt: z.string().describe("연 시각 (ISO 8601)"),
+  lastEditedAt: z
+    .string()
+    .nullable()
+    .describe("이 편집 환경에서 마지막으로 파일을 바꾼 시각. 없으면 null"),
+  lastActiveAt: z.string().describe("마지막 활동 시각 (파일 도구·검사·미리보기)"),
+  idleExpiresAt: z
+    .string()
+    .describe(
+      `이 시각까지 활동이 없으면 잠든다 (마지막 활동 + ${STOREFRONT_EDIT_IDLE_MINUTES}분). 잠들어도 작업 트리는 보존된다`,
+    ),
+  closesAt: z
+    .string()
+    .describe(
+      `이 시각까지 편집 작업(파일 쓰기·검사·버전 만들기·미리보기 링크 발급)이 없으면 서버가 편집 환경을 닫는다 (마지막 편집 작업 + ${STOREFRONT_EDIT_ACTIVITY_TIMEOUT_MINUTES}분). 미리보기만 보고 있어도 닫힌다. 작업 트리는 보존된다`,
+    ),
+});
+export type StorefrontEditSession = z.infer<typeof storefrontEditSessionSchema>;
+
+/** `GET·POST·DELETE /v1/storefront/site/editing` — 편집 환경 상태 */
+export const storefrontEditingSchema = z.object({
+  enabled: z.boolean().describe("편집을 쓸 수 있는가 (플랫폼 스위치와 Sandbox 설정)"),
+  session: storefrontEditSessionSchema
+    .nullable()
+    .describe("열린 편집 환경. 잠들었거나 닫았으면 null"),
+  capacity: z.object({
+    limit: z.number().int().describe("플랫폼 전체 동시 편집 환경 상한"),
+    inUse: z.number().int().describe("지금 열린 편집 환경 수"),
+  }),
+  preview: storefrontEditPreviewSchema.describe(
+    "편집 미리보기 주소 (사이트의 `editPreview`와 같다)",
+  ),
+  workingTree: z.object({
+    modified: z
+      .boolean()
+      .describe("템플릿에서 한 번이라도 고쳤는가 (사이트 `sourceMode`가 `CUSTOM`)"),
+    lastEditedAt: z.string().nullable().describe("마지막으로 파일을 바꾼 시각"),
+  }),
+});
+export type StorefrontEditing = z.infer<typeof storefrontEditingSchema>;
+
+// ─── 파일 ─────────────────────────────────────────────────
+
+export const storefrontFileEntrySchema = z.object({
+  path: z.string(),
+  size: z.number().int().min(0).describe("바이트 수"),
+  hash: storefrontFileHashSchema,
+});
+export type StorefrontFileEntry = z.infer<typeof storefrontFileEntrySchema>;
+
+/** `GET /v1/storefront/site/files?prefix=` — 작업 트리 파일 목록(편집 환경이 없어도 된다. 편집 환경을 깨우지 않는다) */
+export const storefrontFileListSchema = z.object({
+  files: z.array(storefrontFileEntrySchema).describe("경로 사전순"),
+  totalBytes: z.number().int().min(0).describe("작업 트리 전체 바이트 수"),
+});
+export type StorefrontFileList = z.infer<typeof storefrontFileListSchema>;
+
+export const storefrontFileListQuerySchema = z.object({
+  prefix: z
+    .string()
+    .max(256)
+    .optional()
+    .describe("이 접두사로 시작하는 경로만 (예: `src/routes/`)"),
+});
+
+export const storefrontFileContentQuerySchema = z.object({
+  path: z.string().describe("읽을 파일 경로"),
+});
+
+/** `GET /v1/storefront/site/files/content?path=` — 편집 환경이 없어도 된다 */
+export const storefrontFileContentSchema = z.object({
+  path: z.string(),
+  content: z.string().describe("내용 (`encoding`에 따라 텍스트 또는 base64)"),
+  encoding: storefrontFileEncodingSchema,
+  hash: storefrontFileHashSchema,
+  size: z.number().int().min(0),
+});
+export type StorefrontFileContent = z.infer<typeof storefrontFileContentSchema>;
+
+/**
+ * `POST /v1/storefront/site/files/batch` — 여러 파일을 한 번에 쓴다. 편집 환경이 없어도 된다(잠든 작업 트리에 바로 쓰고,
+ * 편집 환경이 떠 있으면 미리보기에 곧바로 반영된다). `expectedHash`: 생략하면 조건 없이 쓴다 · `null`이면 파일이 없어야 한다(새 파일) · 값이면 지금
+ * 해시가 같아야 한다. 조건을 **모두** 확인한 뒤 쓰고, 하나라도 어긋나면 아무것도 쓰지 않는다(409 `FILE_CHANGED`,
+ * `error.details.conflicts`).
+ */
+export const writeStorefrontFilesRequestSchema = z.object({
+  files: z
+    .array(
+      z.object({
+        path: storefrontFilePathSchema,
+        content: z.string().describe("내용 (`encoding`에 따라 텍스트 또는 base64)"),
+        encoding: storefrontFileEncodingSchema.optional().describe("기본 `utf8`"),
+        expectedHash: storefrontFileHashSchema
+          .nullable()
+          .optional()
+          .describe("쓰기 조건. 생략 = 조건 없음 · null = 새 파일 · 값 = 지금 해시가 같을 때만"),
+      }),
+    )
+    .min(1)
+    .max(STOREFRONT_FILE_BATCH_MAX)
+    .refine((files) => new Set(files.map((file) => file.path)).size === files.length, {
+      message: "같은 경로를 두 번 실을 수 없습니다",
+    }),
+});
+export type WriteStorefrontFilesRequest = z.infer<typeof writeStorefrontFilesRequestSchema>;
+
+export const storefrontFileWriteResultSchema = z.object({
+  files: z.array(storefrontFileEntrySchema).describe("쓴 파일의 새 해시·크기 (요청 순서)"),
+});
+export type StorefrontFileWriteResult = z.infer<typeof storefrontFileWriteResultSchema>;
+
+/** 409 `FILE_CHANGED`의 `error.details` */
+export const storefrontFileConflictDetailsSchema = z.object({
+  conflicts: z.array(
+    z.object({
+      path: z.string(),
+      currentHash: storefrontFileHashSchema.nullable().describe("지금 해시. 파일이 없으면 null"),
+    }),
+  ),
+});
+export type StorefrontFileConflictDetails = z.infer<typeof storefrontFileConflictDetailsSchema>;
+
+/** `POST /v1/storefront/site/files/delete` — 없는 파일이면 `deleted: false`(조건을 주면 409 `FILE_CHANGED`) */
+export const deleteStorefrontFileRequestSchema = z.object({
+  path: storefrontFilePathSchema,
+  expectedHash: storefrontFileHashSchema.optional().describe("주면 지금 해시가 같을 때만 지운다"),
+});
+export type DeleteStorefrontFileRequest = z.infer<typeof deleteStorefrontFileRequestSchema>;
+
+export const storefrontFileDeleteResultSchema = z.object({
+  path: z.string(),
+  deleted: z.boolean(),
+});
+export type StorefrontFileDeleteResult = z.infer<typeof storefrontFileDeleteResultSchema>;
+
+/** `POST /v1/storefront/site/files/move` — 이름 바꾸기·옮기기 */
+export const moveStorefrontFileRequestSchema = z.object({
+  from: storefrontFilePathSchema,
+  to: storefrontFilePathSchema,
+  expectedHash: storefrontFileHashSchema.optional().describe("주면 `from`의 지금 해시가 같을 때만"),
+  overwrite: z
+    .boolean()
+    .optional()
+    .describe("`to`에 파일이 있으면 덮는가 (기본 false → 409 `FILE_EXISTS`)"),
+});
+export type MoveStorefrontFileRequest = z.infer<typeof moveStorefrontFileRequestSchema>;
+
+export const storefrontFileMoveResultSchema = z.object({
+  from: z.string(),
+  to: z.string(),
+  hash: storefrontFileHashSchema,
+  size: z.number().int().min(0),
+});
+export type StorefrontFileMoveResult = z.infer<typeof storefrontFileMoveResultSchema>;
+
+/** `POST /v1/storefront/site/files/search` — 텍스트 파일 내용 검색(편집 환경이 없어도 된다) */
+/** 정규식 검색의 패턴 길이 상한 — 편집 Sandbox가 실행 비용을 막으려고 더 좁게 받는다(sandbox-api §4.6) */
+export const STOREFRONT_SEARCH_REGEX_MAX_LENGTH = 100;
+
+export const searchStorefrontFilesRequestSchema = z
+  .object({
+    query: z.string().min(1).max(200),
+    regex: z
+      .boolean()
+      .optional()
+      .describe(
+        "`query`를 정규식으로 본다 (기본 false = 글자 그대로). 정규식은 100자까지이고 중첩 수량자(`(a+)+`)·반복되는 선택(`(a|b)+`)·역참조·뒤 보기, 가변 수량자(`*`·`+`·`?`·`{n,m}`, 넓은 범위는 2로 센다) 차수 4 초과는 400 `INVALID_REQUEST`다. 차수가 클수록 긴 줄은 건너뛰고 비용이 크면 `truncated`로 끊는다",
+      ),
+    caseSensitive: z.boolean().optional().describe("대소문자를 가리는가 (기본 false)"),
+    pathPrefix: z.string().max(256).optional(),
+    maxResults: z.number().int().min(1).max(200).optional().describe("기본 50"),
+  })
+  .refine((body) => !body.regex || body.query.length <= STOREFRONT_SEARCH_REGEX_MAX_LENGTH, {
+    message: `정규식은 ${STOREFRONT_SEARCH_REGEX_MAX_LENGTH}자까지입니다`,
+    path: ["query"],
+  });
+export type SearchStorefrontFilesRequest = z.infer<typeof searchStorefrontFilesRequestSchema>;
+
+export const storefrontFileSearchResultSchema = z.object({
+  matches: z.array(
+    z.object({
+      path: z.string(),
+      line: z.number().int().min(1),
+      column: z.number().int().min(1).optional(),
+      text: z.string().describe("일치한 줄 (일치 앞뒤 200자까지)"),
+    }),
+  ),
+  truncated: z.boolean().describe("`maxResults`에서 끊었는가"),
+});
+export type StorefrontFileSearchResult = z.infer<typeof storefrontFileSearchResultSchema>;
+
+// ─── 검사 ─────────────────────────────────────────────────
+
+/**
+ * `POST /v1/storefront/site/checks` (202) — 작업 트리에 명령 하나를 돌린다(`typecheck` 타입 검사 · `lint` · `test`). 편집 환경이
+ * 없어도 된다(일회용 검사 컨테이너에서 돈다). 검사는 30초를 넘길 수 있어 **항상 202로 검사 id만 주고** 결과는
+ * `GET /v1/storefront/site/checks/{checkId}`로 조회한다(권장 2~3초 간격). 사이트당 끝나지 않은 검사는 하나다 — 같은 종류가 돌고
+ * 있으면 그 검사를 다시 돌려주고, 다른 종류면 409 `CHECK_RUNNING`(`error.details.checkId`)이다. 출력은 꼬리만 준다.
+ */
+export const runStorefrontCheckRequestSchema = z.object({
+  check: z.enum(["typecheck", "lint", "test"]),
+});
+export type RunStorefrontCheckRequest = z.infer<typeof runStorefrontCheckRequestSchema>;
+
+export const storefrontCheckStatusSchema = z
+  .enum(["QUEUED", "RUNNING", "PASSED", "FAILED", "TIMED_OUT", "UNKNOWN"])
+  .describe(
+    "`QUEUED` 대기 · `RUNNING` 실행 중 · `PASSED` 통과 · `FAILED` 실패(명령 실패 또는 `errorCode`) · `TIMED_OUT` 마감(150초)에 걸려 끊김 · `UNKNOWN` 결과를 모른다(다시 실행하지 않는다, 새 검사를 요청한다)",
+  );
+export type StorefrontCheckStatus = z.infer<typeof storefrontCheckStatusSchema>;
+
+/** 끝난 검사 상태 */
+export const STOREFRONT_CHECK_TERMINAL_STATUSES: readonly StorefrontCheckStatus[] = [
+  "PASSED",
+  "FAILED",
+  "TIMED_OUT",
+  "UNKNOWN",
+];
+
+export const storefrontCheckSchema = z.object({
+  checkId: z.string(),
+  check: z.string().describe("`typecheck`·`lint`·`test`"),
+  status: storefrontCheckStatusSchema,
+  exitCode: z.number().int().nullable().describe("명령 종료 코드. 명령이 끝나지 않았으면 null"),
+  durationMs: z.number().int().min(0).nullable().describe("명령 시간. 끝나지 않았으면 null"),
+  outputTail: z.string().nullable().describe("출력 꼬리 (최대 16KiB). 끝나지 않았으면 null"),
+  errorCode: z
+    .string()
+    .nullable()
+    .describe(
+      "명령 밖의 실패 이유 (`CHECK_BUSY`·`SANDBOX_UNAVAILABLE`·`RESULT_UNKNOWN`, 늘어날 수 있다). 명령 결과로 끝났으면 null",
+    ),
+  message: z.string().nullable().describe("`errorCode`가 있을 때 사용자용 안내"),
+  createdAt: z.string(),
+  startedAt: z.string().nullable(),
+  finishedAt: z.string().nullable(),
+});
+export type StorefrontCheck = z.infer<typeof storefrontCheckSchema>;
+
+/** 규칙 심각도 — `error`는 버전 발행을 막는다(빌드 `VERIFY` 실패), `warning`은 알리기만 한다. 없으면 `error`로 본다 */
+export const storefrontRuleSeveritySchema = z.enum(["error", "warning"]);
+export type StorefrontRuleSeverity = z.infer<typeof storefrontRuleSeveritySchema>;
+
+/** 규칙 하나의 검사 결과 — MCP 계측(`mcpRuleResultSchema`)과 같은 모양에 심각도를 더한다 */
+export const storefrontRuleResultSchema = z.object({
+  ruleId: z.string(),
+  status: z.enum(["pass", "violation"]),
+  count: z.number().int().min(0),
+  severity: storefrontRuleSeveritySchema.optional(),
+});
+export type StorefrontRuleResult = z.infer<typeof storefrontRuleResultSchema>;
+
+/**
+ * 규칙 검증 보고서 — `@sayren/mcp`의 `verify_storefront`와 같은 모양이다(원천 `apps/mcp/src/verify.ts`). 위반마다
+ * 고칠 자리(`file`·`line`)와 방법(`fix`·`example`)을 싣는다. `POST /v1/storefront/site/verify`(편집 환경이 잠들어 있어도
+ * 된다)와 빌드의 `verify`가 이 모양이다.
+ */
+export const storefrontVerifyReportSchema = z.object({
+  ok: z.boolean().describe("차단(`error`) 위반이 없는가"),
+  checkedFiles: z.number().int().min(0),
+  summary: z.object({
+    rules: z.number().int(),
+    passed: z.number().int(),
+    violated: z.number().int(),
+    findings: z.number().int(),
+  }),
+  results: z.array(storefrontRuleResultSchema),
+  findings: z.array(
+    z.object({
+      ruleId: z.string(),
+      rule: z.string(),
+      file: z.string(),
+      line: z.number().int().optional(),
+      detail: z.string(),
+      cause: z.string(),
+      fix: z.string(),
+      example: z.string(),
+      doc: z.string(),
+      docUrl: z.string(),
+      templateFile: z.string().optional(),
+      severity: storefrontRuleSeveritySchema.optional(),
+    }),
+  ),
+  message: z.string(),
+  nextSteps: z.array(z.string()),
+});
+export type StorefrontVerifyReport = z.infer<typeof storefrontVerifyReportSchema>;
+
+// ─── 빌드 ─────────────────────────────────────────────────
+
+export const storefrontBuildStatusSchema = z
+  .enum(["QUEUED", "RUNNING", "SUCCEEDED", "FAILED", "TIMED_OUT"])
+  .describe(
+    "`QUEUED` 대기 · `RUNNING` 빌드 중 · `SUCCEEDED` 성공(버전 `READY`) · `FAILED` 실패 · `TIMED_OUT` 시간 초과(10분)",
+  );
+export type StorefrontBuildStatus = z.infer<typeof storefrontBuildStatusSchema>;
+
+/** 끝난 빌드 상태 */
+export const STOREFRONT_BUILD_TERMINAL_STATUSES: readonly StorefrontBuildStatus[] = [
+  "SUCCEEDED",
+  "FAILED",
+  "TIMED_OUT",
+];
+
+/**
+ * 빌드 단계 — 이 순서로 돈다. 첫 실패에서 멈추지만 규칙 검증(`VERIFY`)은 실패해도 타입 검사까지 이어서 해 한 번에 알려 준다.
+ * `UPLOAD`는 사이트 버전 Worker 업로드다(성공하면 발행할 수 있다). 값은 늘어날 수 있다.
+ */
+export const STOREFRONT_BUILD_STAGES = [
+  "VERIFY",
+  "RESTORE",
+  "INSTALL",
+  "TYPECHECK",
+  "BUILD",
+  "BUNDLE",
+  "PACK",
+  "UPLOAD",
+] as const;
+
+export const storefrontBuildSchema = z.object({
+  buildId: z.string(),
+  versionId: z.string(),
+  versionNumber: z.number().int().min(1),
+  status: storefrontBuildStatusSchema,
+  failureStage: z
+    .string()
+    .nullable()
+    .describe(
+      "실패한 단계 (`VERIFY`·`RESTORE`·`INSTALL`·`TYPECHECK`·`BUILD`·`BUNDLE`·`PACK`·`UPLOAD`, 늘어날 수 있다). 실패가 아니면 null",
+    ),
+  errorCode: z
+    .string()
+    .nullable()
+    .describe(
+      "실패 코드 (`RULES_VIOLATED`·`INSTALL_FAILED`·`TYPECHECK_FAILED`·`BUILD_FAILED`·`BUNDLE_FAILED`·`ARTIFACT_INVALID`·`UPLOAD_FAILED`·`SOURCE_NOT_FOUND`·`CAPACITY_EXHAUSTED`·`INTERNAL`, 늘어날 수 있다). 실패가 아니면 null",
+    ),
+  logTail: z.string().nullable().describe("실패 단계 출력 꼬리 (최대 8KB). 없으면 null"),
+  stages: z
+    .array(
+      z.object({
+        stage: z.string(),
+        ok: z.boolean(),
+        durationMs: z.number().int().min(0),
+      }),
+    )
+    .describe("끝난 단계 (도는 순서)"),
+  verify: storefrontVerifyReportSchema
+    .nullable()
+    .describe("규칙 검증 보고서(위반 상세는 50건까지). 그 단계까지 가지 못했으면 null"),
+  queuedAt: z.string(),
+  startedAt: z.string().nullable(),
+  finishedAt: z.string().nullable(),
+  durationMs: z.number().int().nullable().describe("빌드 시간 (시작 → 끝)"),
+});
+export type StorefrontBuild = z.infer<typeof storefrontBuildSchema>;
+
+export const storefrontBuildListQuerySchema = z.object({
+  limit: z.coerce.number().int().min(1).max(50).optional().describe("기본 20, 최신 먼저"),
+});
+
+/**
+ * `POST /v1/storefront/site/versions` — 지금 작업 트리를 고정해 버전을 만든다(빌드 시작). 사이트당 끝나지 않은 빌드는
+ * 하나다(409 `STOREFRONT_BUILD_IN_PROGRESS`). 편집 환경이 없어도 된다.
+ */
+export const createStorefrontVersionRequestSchema = z.object({
+  message: z.string().max(200).optional().describe("버전 메모 (에이전트는 바꾼 내용 요약)"),
+});
+export type CreateStorefrontVersionRequest = z.infer<typeof createStorefrontVersionRequestSchema>;
+
+/** 버전 만들기 응답 (201) — 버전은 `BUILDING`, 빌드는 `QUEUED`로 시작한다. 결과는 `GET builds/{buildId}`로 본다 */
+export const storefrontVersionCreatedSchema = z.object({
+  version: storefrontVersionSchema,
+  build: storefrontBuildSchema,
+});
+export type StorefrontVersionCreated = z.infer<typeof storefrontVersionCreatedSchema>;
+
+/**
+ * `POST /v1/storefront/site/editing/preview-link` — 편집 미리보기(dev 서버) 링크. 콘솔에서 로그인한 OWNER·ADMIN만
+ * 받는다(PAT·에이전트 불가). 5분 안에 열면 그 브라우저에 미리보기 호스트 전용 쿠키(12시간)가 생긴다. 편집 환경이
+ * 없으면 409 `EDIT_SESSION_REQUIRED`다(편집 환경이 `STARTING`이면 링크는 주고, 미리보기 화면이 기동 대기를 보여 준다).
+ */
+export const createStorefrontEditPreviewLinkRequestSchema =
+  createStorefrontPreviewLinkRequestSchema;
+export type CreateStorefrontEditPreviewLinkRequest = CreateStorefrontPreviewLinkRequest;