cafe24-preview
Use when previewing local working-tree CSS/JS changes on a live Cafe24 page before deploying through the admin panel — no HMR, deploy round-trips are slow. Triggers - "/cafe24-preview", "배포 전에 미리 보고 싶
SKILL.mdskills/cafe24-preview/SKILL.md
GitHubCafe24 배포 전 로컬 미리보기 (응답 패치)
Overview
playwright-mcp의 browser_run_code_unsafe로 page.route()를 걸어, 라이브 페이지가 요청하는 리소스를 로컬 수정본으로 바꿔치기(fulfill) 한 상태로 렌더링한다. 주입(append) 방식과 달리 브라우저 실행 "전"에 코드가 대체되므로 JS 중복 실행 문제가 없고, 새로고침해도 패치가 유지된다.
전제: 로컬 HTML은 서버에 넣는 템플릿(입력)이지 완성된 출력이 아니다. {$vars}·모듈이 포함된 마크업은 로컬에서 변수가 안 풀려 미리보기 불가.
미리보기 가능 범위
| 변경 종류 | 미리보기 | 방법 |
|---|---|---|
| 외부 CSS/JS 파일 | ✅ | 파일 요청 인터셉트 → 로컬 내용으로 fulfill |
인라인 <style>/<script> (var-free) |
✅ | HTML 문서 응답 인터셉트 → 블록 마커 단위 치환 |
{$vars}·모듈 포함 마크업 |
❌ | 불가 — 사용자에게 배포 필요 안내 |
Workflow
- 대상 페이지 URL은 사용자에게 물어본다 (탐색하지 말 것). 스킬 인자에 URL이 없으면 AskUserQuestion 등으로 미리보기할 라이브 페이지 URL부터 받는다. curl·크롤링으로 URL을 찾으려 하지 말 것 — labnosh는 비로그인 접근 시
/admin으로 리다이렉트되어 상품 링크 탐색이 불가(실측). - 파일 매핑 검증 (건너뛰지 말 것). 로컬 파일명 ≠ 배포 URL이다. 페이지의 네트워크 요청에서 CSS/JS URL을 확인하고, 로컬 수정 대상 셀렉터/함수가 그 응답 본문에 실제로 있는지 확인한다. 없으면 해당 코드는 인라인 블록으로 배포된 것 → HTML 문서 패치로 전환.
- labnosh 알려진 매핑: 외부 CSS
labnoshhost.mycafe24.com/assets/styles/product.css, 외부 JSassets/scripts/PRODUCT_DETAIL.js. 단 로컬product-detail.css(~2,800줄) 대부분은 템플릿 인라인일 수 있음 — 반드시 실측. - 상세 페이지 URL 형식:
…/product/{이름}/{번호}/…(detail.html?product_no=는 404).
- labnosh 알려진 매핑: 외부 CSS
- 변경분 분류. git diff를 위 표에 따라 분류.
{$vars}포함 변경이 섞여 있으면 그 부분은 미리보기에서 빠진다고 명시. - 라우트 설치. 아래 캐노니컬 코드 사용. Read로 로컬 파일을 읽어 치환 본문을 만든 뒤 코드 문자열에 넣는다.
- reload → 검증 → 즉시 종료. 마커 규칙(
--preview-marker등)이나getComputedStyle실측으로 패치 적용을 확인한다. 적용이 확인되면 거기서 턴을 끝낸다 — 사용자는 브라우저를 기다리고 있다. 검증 중 부수 이슈(캐스케이드 충돌, 다른 규칙이 이김 등)를 발견해도 원인 조사를 벌이지 말고 한 줄 언급만 하고 멈춘다(실측된 불만). 스크린샷은 사용자가 요청할 때만 — 이 스킬의 목적은 사용자가 패치된 페이지를 브라우저에서 직접 보는 것이다. - 열어두기 (기본). 검증 후 라우트를 설치한 채로 페이지를 열어두고 사용자에게 확인하라고 알린다. 라우트는 같은 page 인스턴스에 남아 이후의 다른 MCP 도구 호출·새로고침에도 유지된다. 수정 반복 시
unrouteAll후 재설치. - 정리는 사용자가 끝났다고 할 때만.
page.unrouteAll({ behavior: 'ignoreErrors' })로 원상 복구. 검증 끝났다고 임의로 복구하지 말 것 — 사용자가 보기 전에 패치가 사라진다(실측된 불만).
캐노니컬 코드 (browser_run_code_unsafe)
async (page) => {
await page.unrouteAll({ behavior: 'ignoreErrors' }); // 중복 등록 방지
await page.route('**/assets/styles/product.css*', async (route) => {
try {
const response = await route.fetch();
let body = await response.text();
// 기본은 블록 단위 치환 — 로컬 ≠ 배포본이므로 통째 교체는 스타일 전멸 위험.
// 통째 교체(body = LOCAL_CSS)는 매핑이 1:1로 검증된 경우만.
body = body.replace(원본블록정규식, 수정블록); // 치환 성공 여부를 플래그로 기록해 반환할 것
// 반드시 status/contentType/body 명시형으로 fulfill
await route.fulfill({ status: 200, contentType: 'text/css', body });
} catch (e) {
await route.continue(); // 핸들러 예외 = 요청 통째 실패 → 폴백 필수
}
});
await page.reload({ waitUntil: 'load', timeout: 45000 });
return await page.evaluate(() => /* 패치 적용 검증 */ document.styleSheets.length);
}
HTML 문서 패치는 라우트 패턴을 페이지 URL로, 핸들러 첫 줄에 if (route.request().resourceType() !== 'document') return route.continue(); 추가, contentType은 'text/html; charset=utf-8'.
Common Mistakes (전부 실측된 실패)
| 실수 | 결과 / 올바른 방법 |
|---|---|
Buffer.byteLength로 content-length 계산 |
Buffer is not defined — 샌드박스에 Node 전역 없음. fulfill이 알아서 계산하므로 헤더 손대지 말 것 |
route.fulfill({ response, body }) (원본 response 재사용형) |
조용히 실패 — 패치 미적용인데 에러도 없음. { status, contentType, body } 명시형만 사용 |
| 핸들러 try/catch 없음 | 예외 시 해당 리소스가 통째로 로드 안 됨 (스타일 전멸) |
unrouteAll 없이 재등록 |
이전 핸들러(실패본 포함)가 중첩 실행 |
| 매핑 검증 생략, 파일명만 보고 인터셉트 | 로컬 파일과 배포 파일이 달라 "패치했는데 그대로"로 보임 |
| 배포본을 로컬 파일로 통째 교체 | 배포본에만 있는 규칙이 사라져 스타일 전멸 — 블록 단위 치환이 기본 |
| 치환 성공 여부 확인 없이 fulfill | 정규식 미매칭 시 원본 그대로 서빙되어 "패치했는데 그대로" — 치환 여부를 플래그로 반환할 것 |
{$vars} 포함 블록을 치환 |
날 변수 텍스트 노출로 페이지 깨짐 |
| 검증을 주입 방식 습관대로 "새로고침 금지"로 진행 | 불필요한 제약 — 응답 패치는 새로고침에도 유지됨. 오히려 reload가 정상 검증 경로 |
| 패치 적용 확인 후에도 부수 이슈 원인 조사를 계속 진행 | 사용자는 브라우저만 기다리는 중 — "띄우고 끝"이 역할. 발견 사항은 한 줄 언급 후 즉시 종료(실측된 불만) |