@sayren/mcp 0.1.0

package/dist/index.mjs

@@ -0,0 +1,361 @@
+#!/usr/bin/env node
+import { readFileSync, readdirSync, statSync } from "node:fs";
+import { readdir } from "node:fs/promises";
+import { dirname, join, relative, sep } from "node:path";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { fileURLToPath } from "node:url";
+
+//#region src/config.ts
+const DEFAULT_API_ORIGIN = "https://api.sayren.app";
+function loadConfig(env = process.env) {
+	const token = env.SAYREN_TOKEN?.trim();
+	if (!token) throw new Error("SAYREN_TOKEN이 없어요. 셀러 콘솔 개발자 공간 › API 토큰에서 발급한 토큰을 MCP 설정의 env에 넣어주세요");
+	const origin = (env.SAYREN_API_ORIGIN ?? DEFAULT_API_ORIGIN).replace(/\/+$/, "");
+	return {
+		adminBaseUrl: `${origin}/v1`,
+		storefrontBaseUrl: `${origin}/storefront/v1`,
+		token
+	};
+}
+
+//#endregion
+//#region src/rules.ts
+const RULES = [
+	{
+		id: "server-only-env",
+		title: "`process.env`는 `*.server.ts`에만 둔다",
+		why: "브라우저 번들에 들어가면 `process is not defined`로 그 화면 모듈이 통째로 깨진다. 결제 화면에서 터지면 결제가 시작조차 안 된다"
+	},
+	{
+		id: "tenant-header",
+		title: "테넌트는 `X-Store-Code` 헤더로 보낸다",
+		why: "공유 API 호스트에서 스토어를 가르는 값이다. 빠지면 다른 스토어 데이터가 보이거나 404가 난다"
+	},
+	{
+		id: "no-module-token",
+		title: "토큰을 모듈 전역에 담지 않는다",
+		why: "서버 렌더는 요청을 공유한다. 전역에 담으면 다른 구매자의 요청에 토큰이 섞인다"
+	},
+	{
+		id: "loader-first",
+		title: "데이터는 loader에서 받는다",
+		why: "클라이언트에서 다시 받으면 첫 화면이 비고 검색 노출이 죽는다. SSR을 끄지 않는다"
+	},
+	{
+		id: "popup-sync-open",
+		title: "결제 팝업은 클릭 콜스택에서 동기적으로 연다",
+		why: "API 응답을 기다린 뒤 열면 브라우저가 팝업을 막는다. 빈 창을 먼저 열고 주소를 넣는다"
+	},
+	{
+		id: "popup-client-submit",
+		title: "주문서 제출은 클라이언트 제출(`<Form>`)로 한다",
+		why: "네이티브 폼은 문서를 다시 그려 팝업 제어 상태가 사라진다. 결제창이 빈 창으로 남는다"
+	},
+	{
+		id: "parent-origin",
+		title: "결제 요청에 우리 화면의 origin을 실어 보낸다",
+		why: "결제 팝업은 그 값으로만 부모 창에 결과를 알린다. 빠지면 결제는 되는데 주문서가 완료를 못 받는다"
+	},
+	{
+		id: "popup-origin-check",
+		title: "팝업 메시지는 origin과 source를 모두 검증한다",
+		why: "검증 없이 받으면 아무 창이나 결제 완료를 흉내 낼 수 있다"
+	},
+	{
+		id: "closed-not-failed",
+		title: "팝업이 결과 없이 닫히면 실패로 단정하지 않는다",
+		why: "이미 승인됐을 수 있다. 서버에 결제 상태를 물어봐야 이중 결제와 누락 주문을 막는다"
+	}
+];
+/** 주석을 걷어낸다 — 규칙을 설명하는 주석이 위반으로 잡히지 않게 한다 */
+function stripComments(source) {
+	return source.replace(/\/\*[\s\S]*?\*\//g, " ").replace(/(^|[^:])\/\/[^\n]*/g, "$1 ");
+}
+const CLIENT_FILE = /\.(ts|tsx)$/;
+const SERVER_FILE = /\.server\.(ts|tsx)$/;
+/**
+* 만들어진 프로젝트의 소스를 규칙과 대조한다. 정적 검사라 모든 문제를 잡지는 못하지만,
+* 이 아홉 가지는 실제로 반복해서 깨지는 것들이다.
+*/
+function verifySources(files) {
+	const findings = [];
+	const cleaned = files.map((file) => ({
+		path: file.path,
+		content: stripComments(file.content)
+	}));
+	const has = (needle) => cleaned.some((file) => file.content.includes(needle));
+	for (const file of cleaned) {
+		if (!CLIENT_FILE.test(file.path)) continue;
+		if (!(SERVER_FILE.test(file.path) || /\/(server|\.server)\//.test(file.path)) && /process\.env\.[A-Z_]/.test(file.content)) findings.push({
+			ruleId: "server-only-env",
+			file: file.path,
+			detail: "브라우저로 갈 수 있는 파일에서 process.env를 읽는다. `*.server.ts`로 옮긴다"
+		});
+		if (/createStorefrontClient\(/.test(file.content) && !/storeCode/.test(file.content)) findings.push({
+			ruleId: "tenant-header",
+			file: file.path,
+			detail: "API 클라이언트를 만들 때 storeCode를 주지 않는다"
+		});
+		if (/^(const|let)\s+\w*[Tt]oken\s*=\s*["'`]/m.test(file.content)) findings.push({
+			ruleId: "no-module-token",
+			file: file.path,
+			detail: "토큰처럼 보이는 값을 모듈 전역에 두었다"
+		});
+		if (/window\.open\(/.test(file.content) && /await .*\n?.*window\.open\(/.test(file.content)) findings.push({
+			ruleId: "popup-sync-open",
+			file: file.path,
+			detail: "await 뒤에 팝업을 연다. 브라우저가 막는다"
+		});
+		if (/addEventListener\("message"/.test(file.content)) {
+			if (!/event\.origin|\.origin\s*!==/.test(file.content)) findings.push({
+				ruleId: "popup-origin-check",
+				file: file.path,
+				detail: "message 리스너가 origin을 검증하지 않는다"
+			});
+			if (!/event\.source|\.source\s*!==/.test(file.content)) findings.push({
+				ruleId: "popup-origin-check",
+				file: file.path,
+				detail: "message 리스너가 source(우리가 연 창)를 검증하지 않는다"
+			});
+		}
+		if (/requestPayment\(/.test(file.content) && /<form\s/.test(file.content)) findings.push({
+			ruleId: "popup-client-submit",
+			file: file.path,
+			detail: "결제 화면이 네이티브 <form>을 쓴다. react-router의 <Form>으로 바꾼다"
+		});
+	}
+	if (has("requestPayment(") && !has("Origin")) findings.push({
+		ruleId: "parent-origin",
+		file: "(프로젝트 전체)",
+		detail: "결제 요청에 Origin 헤더를 싣는 코드가 없다"
+	});
+	if (has("requestPayment(") && !has("getStatus(")) findings.push({
+		ruleId: "closed-not-failed",
+		file: "(프로젝트 전체)",
+		detail: "팝업이 결과 없이 닫힌 경우 결제 상태를 조회하는 코드가 없다"
+	});
+	if (has("createStorefrontClient(") && !has("loader")) findings.push({
+		ruleId: "loader-first",
+		file: "(프로젝트 전체)",
+		detail: "loader에서 데이터를 받는 코드가 없다. 클라이언트 전용으로 그리면 SSR이 죽는다"
+	});
+	return findings;
+}
+
+//#endregion
+//#region src/store-context.ts
+async function callApi(url, init = {}) {
+	const response = await fetch(url, init);
+	const body = await response.json().catch(() => null);
+	if (!response.ok) {
+		const code = body?.error?.code ?? String(response.status);
+		const message = body?.error?.message ?? "요청이 실패했어요";
+		throw new Error(`${code}: ${message}`);
+	}
+	return body?.data ?? body;
+}
+async function fetchStoreContext(config$1) {
+	const authHeaders = { authorization: `Bearer ${config$1.token}` };
+	const store = await callApi(`${config$1.adminBaseUrl}/store`, { headers: authHeaders });
+	const storeHeaders = { "x-store-code": store.storeCode };
+	const [categories, products, paymentSettings] = await Promise.all([
+		callApi(`${config$1.storefrontBaseUrl}/categories`, { headers: storeHeaders }),
+		callApi(`${config$1.storefrontBaseUrl}/products?size=5`, { headers: storeHeaders }),
+		callApi(`${config$1.adminBaseUrl}/store/payment-settings`, { headers: authHeaders }).catch(() => null)
+	]);
+	const connected = (paymentSettings?.providers ?? []).filter((p) => p.connected && p.enabled);
+	return {
+		storeId: store.storeId,
+		storeCode: store.storeCode,
+		name: store.name,
+		logoUrl: store.logoUrl,
+		storefrontUrl: store.storefrontUrl,
+		storefrontApiBaseUrl: config$1.storefrontBaseUrl,
+		categories: categories.map((category) => ({
+			categoryId: category.categoryId,
+			name: category.name
+		})),
+		productCount: products.totalElements,
+		sampleProducts: products.contents,
+		payment: {
+			connectedProviders: connected.map((p) => p.provider),
+			sandboxOnly: connected.length === 0 || connected.every((p) => p.sandboxMode)
+		}
+	};
+}
+
+//#endregion
+//#region src/template.ts
+/**
+* 스토어프론트 템플릿 파일 제공.
+*
+* 템플릿은 저장소 안에 있는 **실제로 도는 앱**이다. CI가 이 앱을 빌드·테스트하므로,
+* 에이전트가 받아 쓰는 코드가 항상 동작하는 상태다. 즉석에서 지어낸 코드와 다른 점이 여기다.
+*/
+const HERE = dirname(fileURLToPath(import.meta.url));
+/** 번들에 복사된 template/ 이 먼저이고, 저장소에서 바로 실행할 때는 templates/ 를 쓴다 */
+const CANDIDATES = [join(HERE, "..", "template"), join(HERE, "..", "..", "..", "templates", "storefront-react-router")];
+const SKIP_DIRS = new Set([
+	"node_modules",
+	"build",
+	".react-router",
+	"dist",
+	".git"
+]);
+function resolveRoot() {
+	for (const candidate of CANDIDATES) try {
+		if (statSync(candidate).isDirectory()) return candidate;
+	} catch {}
+	throw new Error("스토어프론트 템플릿을 찾지 못했어요");
+}
+const TEMPLATE_ROOT = resolveRoot();
+function walk(dir, acc) {
+	for (const entry of readdirSync(dir, { withFileTypes: true })) {
+		if (entry.name.startsWith(".") && entry.name !== ".gitignore") continue;
+		if (SKIP_DIRS.has(entry.name)) continue;
+		const full = join(dir, entry.name);
+		if (entry.isDirectory()) walk(full, acc);
+		else acc.push(relative(TEMPLATE_ROOT, full).split(sep).join("/"));
+	}
+	return acc;
+}
+function listTemplateFiles() {
+	return walk(TEMPLATE_ROOT, []).sort();
+}
+/** 경로 탈출을 막는다 — 목록에 있는 파일만 읽는다 */
+function readTemplateFile(path) {
+	const normalized = path.replace(/^\.?\//, "");
+	if (!listTemplateFiles().includes(normalized)) throw new Error(`템플릿에 없는 파일이에요: ${path}`);
+	return readFileSync(join(TEMPLATE_ROOT, normalized), "utf8");
+}
+
+//#endregion
+//#region src/index.ts
+const config = loadConfig();
+const server = new McpServer({
+	name: "sayren",
+	version: "0.1.0"
+});
+const text = (value) => ({ content: [{
+	type: "text",
+	text: typeof value === "string" ? value : JSON.stringify(value, null, 2)
+}] });
+server.registerTool("get_store_context", {
+	title: "스토어 컨텍스트",
+	description: "연결된 스토어의 사실을 모아 준다. 스토어 코드, 스토어프론트 API 주소, 카테고리, 상품 표본, 결제 설정 상태다. 화면을 만들기 전에 먼저 부른다 — 카테고리와 상품을 지어내지 않게 한다.",
+	inputSchema: {}
+}, async () => text(await fetchStoreContext(config)));
+server.registerTool("get_scaffold_plan", {
+	title: "스토어프론트 생성 계획",
+	description: "React Router(SSR) 스토어프론트를 만드는 순서와 지켜야 할 규칙, 그리고 템플릿 파일 목록을 준다. 구현을 시작하기 전에 부른다.",
+	inputSchema: {}
+}, async () => {
+	const store = await fetchStoreContext(config).catch(() => null);
+	return text({
+		steps: [
+			"1. `list_template_files`로 파일 목록을 받는다.",
+			"2. 각 파일을 `get_template_file`로 받아 **그대로** 프로젝트에 쓴다. 코드를 새로 짓지 않는다.",
+			"3. `.env`에 `SAYREN_API_URL`과 `SAYREN_STORE_CODE`를 넣는다(아래 값).",
+			"4. `pnpm install` 후 `pnpm dev`로 띄워 홈에 상품이 보이는지 확인한다.",
+			"5. 사용자가 원하는 디자인은 확장 지점에서만 바꾼다.",
+			"6. 끝나면 `verify_storefront`로 규칙 위반이 없는지 확인한다."
+		],
+		env: store ? {
+			SAYREN_API_URL: store.storefrontApiBaseUrl,
+			SAYREN_STORE_CODE: store.storeCode
+		} : {
+			SAYREN_API_URL: config.storefrontBaseUrl,
+			SAYREN_STORE_CODE: "(get_store_context 참고)"
+		},
+		extensionPoints: [
+			{
+				what: "브랜드 색·서체",
+				where: "app/app.css의 @theme"
+			},
+			{
+				what: "헤더·전역 내비",
+				where: "app/components/site-header.tsx"
+			},
+			{
+				what: "상품 카드",
+				where: "app/components/product-card.tsx"
+			},
+			{
+				what: "화면 추가",
+				where: "app/routes.ts"
+			}
+		],
+		doNotTouch: [
+			"app/lib/payment-popup.ts — 결제 팝업 규칙",
+			"app/lib/api.server.ts — 테넌트 헤더·토큰 전달·부모 origin",
+			"loader에서 데이터를 받는 구조"
+		],
+		rules: RULES,
+		templateFiles: listTemplateFiles()
+	});
+});
+server.registerTool("list_template_files", {
+	title: "템플릿 파일 목록",
+	description: "검증된 스토어프론트 템플릿의 파일 목록이다. 이 목록 그대로 프로젝트를 만든다.",
+	inputSchema: {}
+}, async () => text({ files: listTemplateFiles() }));
+server.registerTool("get_template_file", {
+	title: "템플릿 파일 내용",
+	description: "템플릿 파일 하나의 원문을 준다. 받은 내용을 그대로 쓴다 — 이 코드는 CI가 빌드·테스트해 동작을 보장하는 소스다.",
+	inputSchema: { path: z.string().describe("`list_template_files`가 준 경로") }
+}, async ({ path }) => text(readTemplateFile(path)));
+server.registerTool("verify_storefront", {
+	title: "생성 결과 검증",
+	description: "만들어진 프로젝트를 규칙과 대조한다. 결제가 조용히 실패하는 실수(브라우저 번들의 process.env, 팝업 origin 미검증, 부모 origin 누락 등)를 잡는다.",
+	inputSchema: { projectDir: z.string().describe("검사할 프로젝트 경로(절대 경로)") }
+}, async ({ projectDir }) => {
+	const files = await collectSources(projectDir);
+	if (!files.length) return text({
+		ok: false,
+		message: `소스를 찾지 못했어요: ${projectDir}`
+	});
+	const findings = verifySources(files);
+	return text({
+		ok: findings.length === 0,
+		checkedFiles: files.length,
+		findings: findings.map((finding) => ({
+			...finding,
+			rule: RULES.find((rule) => rule.id === finding.ruleId)
+		})),
+		message: findings.length === 0 ? "규칙 위반을 찾지 못했어요. 직접 띄워 결제까지 한 번 해보세요" : "아래 항목을 고친 뒤 다시 검사해주세요"
+	});
+});
+const SKIP = new Set([
+	"node_modules",
+	"build",
+	"dist",
+	".react-router",
+	".git"
+]);
+async function collectSources(dir) {
+	try {
+		if (!statSync(dir).isDirectory()) return [];
+	} catch {
+		return [];
+	}
+	const out = [];
+	const walk$1 = async (current) => {
+		for (const entry of await readdir(current, { withFileTypes: true })) {
+			if (SKIP.has(entry.name) || entry.name.startsWith(".")) continue;
+			const full = join(current, entry.name);
+			if (entry.isDirectory()) await walk$1(full);
+			else if (/\.(ts|tsx|js|jsx)$/.test(entry.name)) out.push({
+				path: relative(dir, full).split(sep).join("/"),
+				content: readFileSync(full, "utf8")
+			});
+		}
+	};
+	await walk$1(dir);
+	return out;
+}
+await server.connect(new StdioServerTransport());
+
+//#endregion
+export {  };

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@sayren/mcp",
+  "version": "0.1.0",
+  "type": "module",
+  "bin": {
+    "sayren-mcp": "./dist/index.mjs"
+  },
+  "files": [
+    "dist",
+    "template"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.22.0",
+    "zod": "^4.6.5",
+    "@sayren/store-sdk": "0.1.0",
+    "@sayren/storefront-sdk": "0.1.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.5.14",
+    "@types/node": "^24.13.5",
+    "tsdown": "^0.16.4",
+    "tsx": "^4.20.3",
+    "typescript": "^6.0.3",
+    "vitest": "^5.0.1"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cochoio/shop.24.git"
+  },
+  "description": "sayren MCP 서버 — 스토어 컨텍스트 조회와 스토어프론트 생성",
+  "scripts": {
+    "dev": "tsx src/index.ts",
+    "build": "tsdown && node scripts/copy-template.mjs",
+    "lint": "biome check --write . && tsc --noEmit",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}

package/template/.env

@@ -0,0 +1,2 @@
+SAYREN_API_URL=http://localhost:4001/storefront/v1
+SAYREN_STORE_CODE=mystore

package/template/README.md

@@ -0,0 +1,42 @@
+# 스토어프론트 템플릿 (React Router SSR)
+
+sayren MCP가 내려주는 스토어프론트 시작점이다. 구매 흐름 전체가 이미 붙어 있다.
+홈, 목록·검색, 상세, 장바구니, 주문서·결제 팝업, 완료, 로그인, 주문 내역이다.
+
+## 시작하기
+
+```bash
+pnpm install
+SAYREN_API_URL=https://api.sayren.app/storefront/v1 \
+SAYREN_STORE_CODE=mystore \
+pnpm dev
+```
+
+| 환경변수 | 뜻 |
+| --- | --- |
+| `SAYREN_API_URL` | 스토어프론트 API 베이스 |
+| `SAYREN_STORE_CODE` | 테넌트 스토어 코드. 서브도메인으로 서비스하면 비워 둔다 |
+
+## 확장 지점
+
+| 자리 | 파일 |
+| --- | --- |
+| 브랜드 색·서체 | `app/app.css`의 `@theme` |
+| 헤더·전역 내비 | `app/components/site-header.tsx` |
+| 상품 카드 | `app/components/product-card.tsx` |
+| 화면 추가 | `app/routes.ts` |
+
+## 건드리지 않는 편이 좋은 것
+
+- `app/lib/payment-popup.ts` — 결제 팝업 규칙이다. 팝업은 클릭 콜스택에서 동기적으로 열고,
+  postMessage는 origin과 source를 모두 검증하며, 결과 없이 닫히면 서버에 상태를 물어본다.
+  하나라도 어기면 결제가 조용히 실패한다.
+- `app/lib/api.ts` — 테넌트 헤더와 토큰 전달 방식이다. 토큰을 모듈 전역에 담으면 서버 렌더에서
+  다른 사용자의 요청에 섞인다.
+- loader에서 데이터를 받아 그리는 구조 — 클라이언트에서 다시 받으면 검색 노출과 첫 화면이 죽는다.
+
+## 주의
+
+- 주문서(`/checkout`)는 들어올 때마다 주문서 세션을 새로 만든다. 조회 API가 없고, 가격과 재고를
+  매번 다시 계산해야 하기 때문이다.
+- 비회원 장바구니는 서버가 발급한 토큰으로만 찾는다. 쿠키를 지우면 담은 상품이 사라진다.

package/template/app/app.css

@@ -0,0 +1,22 @@
+@import "tailwindcss";
+/* 상세설명이 에디터가 내보낸 HTML이라 그 모양 규칙이 필요하다 — 사진 줄, 재생기 틀,
+   구분선. 활자는 product-description.tsx가 정하고 이 파일은 건드리지 않는다. */
+@import "@avarlabs/editor/styles/reader.css";
+
+/*
+ * 확장 지점 — 브랜드 색과 서체는 여기서 바꾼다. 화면 코드는 토큰만 쓰므로
+ * 이 블록만 고쳐도 전체 톤이 바뀐다.
+ */
+@theme {
+  --color-ink: #202429;
+  --color-muted: #5f6773;
+  --color-line: #ededed;
+  --color-chip: #f5f5f5;
+  --color-point: #ff204b;
+  --font-sans: "Pretendard Variable", Pretendard, -apple-system, "Apple SD Gothic Neo", sans-serif;
+}
+
+html {
+  font-family: var(--font-sans);
+  word-break: keep-all;
+}

package/template/app/components/product-card.tsx

@@ -0,0 +1,45 @@
+import type { ProductCard as ProductCardData } from "@sayren/storefront-sdk";
+import { Link } from "react-router";
+import { formatPrice } from "../lib/format";
+
+/** 상품 카드 — 확장 지점: 찜 버튼·리뷰 별점 같은 요소는 여기에 붙인다 */
+export function ProductCard({ product }: { product: ProductCardData }) {
+  const price = product.discountedPrice ?? product.salePrice;
+
+  return (
+    <Link to={`/products/${product.productId}`} className="group flex flex-col gap-2">
+      <div className="relative aspect-square overflow-hidden rounded-lg bg-chip">
+        <img
+          src={product.thumbnailUrl}
+          alt=""
+          className="h-full w-full object-cover transition group-hover:scale-105"
+          loading="lazy"
+        />
+        {product.soldOut ? (
+          <span className="absolute inset-0 flex items-center justify-center bg-white/70 font-semibold text-sm">
+            품절
+          </span>
+        ) : null}
+      </div>
+      <div className="flex flex-col gap-1">
+        <span className="line-clamp-2 text-sm">{product.name}</span>
+        <span className="flex items-baseline gap-2">
+          {product.discountRate ? (
+            <span className="font-bold text-point">{product.discountRate}%</span>
+          ) : null}
+          <span className="font-bold">{formatPrice(price)}</span>
+          {product.discountedPrice != null ? (
+            <span className="text-muted text-xs line-through">
+              {formatPrice(product.salePrice)}
+            </span>
+          ) : null}
+        </span>
+        {product.reviewCount > 0 ? (
+          <span className="text-muted text-xs">
+            리뷰 {product.reviewCount}개 · 평점 {product.averageRating.toFixed(1)}
+          </span>
+        ) : null}
+      </div>
+    </Link>
+  );
+}

package/template/app/components/product-description.tsx

@@ -0,0 +1,28 @@
+/**
+ * 상품 상세설명 렌더.
+ *
+ * 상세설명은 셀러가 콘솔 에디터로 쓴 HTML이다. API가 **쓰기 시점에 허용목록으로 정화한
+ * HTML만 저장**하므로(@avarlabs/editor의 허용목록) 그대로 그려도 된다.
+ *
+ * 단, 그 기능 이전에 저장된 레거시 평문은 정화된 적이 없다. 그래서 "HTML인지"를
+ * 단순히 '<' 포함이 아니라 **에디터가 생성하는 블록 태그로 시작하는지**로 판별한다.
+ * 레거시 평문(`10<20`, `<img onerror=...>`)은 이 패턴으로 시작하지 않으므로 평문 분기로
+ * 가 React가 이스케이프 렌더 → XSS·표시 깨짐이 모두 방지된다.
+ *
+ * 확장 지점 — 활자(본문 크기·제목·인용)는 아래 클래스가 정한다. 사진 줄·재생기 틀·
+ * 구분선 같은 에디터 고유 모양은 `app.css`가 불러오는 reader.css가 맡는다.
+ */
+const EDITOR_HTML_START = /^\s*<(?:p|h[1-6]|ul|ol|hr|figure|table|blockquote|pre)[\s>/]/i;
+
+export function ProductDescription({ description }: { description: string }) {
+  if (!EDITOR_HTML_START.test(description)) {
+    return <p className="whitespace-pre-line text-sm leading-relaxed">{description}</p>;
+  }
+  return (
+    <div
+      className="text-sm leading-relaxed [&_a]:underline [&_blockquote]:my-4 [&_blockquote]:border-line [&_blockquote]:border-l-2 [&_blockquote]:pl-4 [&_figcaption]:mt-2 [&_figcaption]:text-center [&_figcaption]:text-muted [&_figcaption]:text-xs [&_figure]:my-5 [&_h2]:mt-4 [&_h2]:mb-2 [&_h2]:font-bold [&_h2]:text-lg [&_h3]:mt-3 [&_h3]:mb-1 [&_h3]:font-semibold [&_h3]:text-base [&_hr]:my-4 [&_img]:max-w-full [&_ol]:list-decimal [&_ol]:pl-5 [&_pre]:my-4 [&_pre]:overflow-x-auto [&_pre]:rounded-lg [&_pre]:bg-chip [&_pre]:p-4 [&_pre]:text-xs [&_table]:my-4 [&_table]:w-full [&_table]:border-collapse [&_td]:border [&_td]:border-line [&_td]:p-2 [&_th]:border [&_th]:border-line [&_th]:bg-chip [&_th]:p-2 [&_ul]:list-disc [&_ul]:pl-5"
+      // biome-ignore lint/security/noDangerouslySetInnerHtml: 에디터 블록 태그로 시작하는 콘텐츠만 진입 — 서버 쓰기 시점 정화 불변식 신뢰 (위 주석)
+      dangerouslySetInnerHTML={{ __html: description }}
+    />
+  );
+}

package/template/app/components/site-header.tsx

@@ -0,0 +1,25 @@
+import { Link } from "react-router";
+
+/** 확장 지점 — 로고·전역 내비게이션은 여기서 바꾼다 */
+export function SiteHeader() {
+  return (
+    <header className="border-line border-b">
+      <div className="mx-auto flex w-full max-w-5xl items-center justify-between px-4 py-4">
+        <Link to="/" className="font-bold text-lg">
+          스토어
+        </Link>
+        <nav className="flex items-center gap-4 text-sm">
+          <Link to="/products" className="hover:text-point">
+            전체 상품
+          </Link>
+          <Link to="/cart" className="hover:text-point">
+            장바구니
+          </Link>
+          <Link to="/orders" className="hover:text-point">
+            주문 내역
+          </Link>
+        </nav>
+      </div>
+    </header>
+  );
+}

package/template/app/lib/api.server.ts

@@ -0,0 +1,34 @@
+import { createStorefrontClient } from "@sayren/storefront-sdk";
+import { API_BASE_URL, resolveStoreCode } from "./config.server";
+
+/**
+ * 서버(loader·action)에서 쓰는 스토어프론트 API 클라이언트.
+ *
+ * 테넌트는 `X-Store-Code` 헤더로 보낸다. 토큰은 요청마다 넘긴다 — 모듈 전역에 담으면 서버 렌더에서
+ * 다른 사용자의 요청에 섞인다.
+ *
+ * 비회원 장바구니 토큰은 서버가 새로 발급할 수 있다. `onCartToken`으로 받아 쿠키에 다시 심는다.
+ */
+export function apiFor(
+  request: Request,
+  options: {
+    accessToken?: string | null;
+    cartToken?: string | null;
+    onCartToken?: (token: string) => void;
+  } = {},
+) {
+  return createStorefrontClient({
+    baseUrl: API_BASE_URL,
+    storeCode: resolveStoreCode(request),
+    accessToken: options.accessToken ?? undefined,
+    cartToken: options.cartToken ?? undefined,
+    onCartToken: options.onCartToken,
+    // 결제 요청에 우리 화면의 origin을 실어 보낸다. 결제 팝업은 이 값으로만 부모 창에
+    // 결과를 알린다 — 빠지면 결제는 되지만 주문서가 완료를 못 받는다.
+    fetch: (input, init) => {
+      const headers = new Headers(init?.headers);
+      headers.set("Origin", new URL(request.url).origin);
+      return fetch(input, { ...init, headers });
+    },
+  });
+}

package/template/app/lib/api.ts

@@ -0,0 +1,7 @@
+import { createStorefrontClient } from "@sayren/storefront-sdk";
+import type { PublicConfig } from "./config";
+
+/** 브라우저용 — loader가 내려준 설정으로 만든다(결제 상태 폴링에 쓴다) */
+export function browserApi(config: PublicConfig) {
+  return createStorefrontClient({ baseUrl: config.apiBaseUrl, storeCode: config.storeCode });
+}

package/template/app/lib/cart-session.server.ts

@@ -0,0 +1,18 @@
+import { createCookie } from "react-router";
+
+/**
+ * 비회원 장바구니 토큰 — 서버가 `X-Cart-Token` 헤더로 발급한다. 회원은 액세스 토큰으로
+ * 장바구니를 찾지만 비회원은 이 토큰이 유일한 열쇠라, 잃어버리면 담은 상품이 사라진다.
+ */
+export const cartCookie = createCookie("sayren_cart", {
+  httpOnly: true,
+  sameSite: "lax",
+  path: "/",
+  secure: process.env.NODE_ENV === "production",
+  maxAge: 60 * 60 * 24 * 30,
+});
+
+export async function readCartToken(request: Request): Promise<string | null> {
+  const value = await cartCookie.parse(request.headers.get("cookie"));
+  return typeof value === "string" && value ? value : null;
+}

package/template/app/lib/checkout-intent.ts

@@ -0,0 +1,30 @@
+/**
+ * 주문서 진입 의도 — URL 파라미터로 받는다.
+ *
+ * 스토어프론트 API에는 "만들어 둔 주문서 다시 조회"가 없다. 주문서 세션은 만들 때 한 번 내려오고
+ * 짧게 만료된다. 그래서 주문서 화면은 들어올 때마다 세션을 새로 만든다. 조건이 URL에 있으면
+ * 새로고침·뒤로가기·링크 공유가 그대로 동작한다.
+ *
+ * 값을 사용자가 바꿀 수 있지만 위험하지 않다. 장바구니 항목은 장바구니 토큰으로 소유가 확인되고,
+ * 가격·재고는 서버가 다시 계산한다.
+ */
+export interface CheckoutIntent {
+  cartItemIds?: string[];
+  directItem?: { productId: string; optionId?: string; quantity: number };
+}
+
+export function checkoutIntentFrom(params: URLSearchParams): CheckoutIntent | null {
+  const cartItemIds = params.getAll("cartItemId").filter(Boolean);
+  if (cartItemIds.length) return { cartItemIds };
+
+  const productId = params.get("productId");
+  if (!productId) return null;
+  const quantity = Number(params.get("quantity") ?? 1);
+  return {
+    directItem: {
+      productId,
+      optionId: params.get("optionId") ?? undefined,
+      quantity: Number.isFinite(quantity) && quantity > 0 ? Math.floor(quantity) : 1,
+    },
+  };
+}