sns-auto-builder 1.0.0

package/scripts/chatgpt-image-gen.js

@@ -0,0 +1,400 @@
+#!/usr/bin/env node
+/**
+ * sns-auto-builder — ChatGPT 웹 UI 이미지 생성기
+ *
+ * `openai-image-gen.js` 의 형제. 다른 점은 **API 를 안 쓴다**는 것뿐이다.
+ * 로그인된 Chrome 프로필(.chrome-profile)을 puppeteer 로 몰아 chatgpt.com 에
+ * 프롬프트를 한 장씩 넣고 나온 이미지를 받아온다. → API 키 불필요, Plus 구독으로 처리.
+ *
+ * CLI/JSON 스키마는 openai-image-gen.js 와 동일하다 (templates/slides.*.json).
+ * 크롭도 그 스크립트의 cropTo45 를 그대로 재사용한다 → 두 트랙의 배율이 항상 같다.
+ *
+ * ⚠️ 이 트랙도 한글이 이미지 안에 들어간다. 매번 달라지므로 9장 전부 눈으로 확인해라.
+ *
+ * 사용법:
+ *   node scripts/chatgpt-image-gen.js --topic my-topic --slides templates/slides.my-topic.json
+ *   node scripts/chatgpt-image-gen.js --topic my-topic --slides ... --ref output/_refs/123/ref-01.png
+ *   node scripts/chatgpt-image-gen.js --topic my-topic --slides ... --only 3
+ *   node scripts/chatgpt-image-gen.js --topic my-topic --slides ... --dry-run
+ *
+ * 이어서 돌리기:
+ *   이미 있는 PNG 는 자동으로 건너뛴다. 호출자 타임아웃(예: Bash 툴 2분)에 잘려도
+ *   같은 명령을 다시 부르면 남은 장부터 이어서 돈다. 전부 다시 뽑으려면 --force.
+ *
+ * 브라우저:
+ *   기본 — .chrome-profile 로 Chrome 을 직접 띄운다. 그 프로필로 이미 Chrome 이
+ *          떠 있으면(예: chrome-devtools MCP) 프로필이 잠겨 실패한다. 그때는
+ *   --browser-url http://127.0.0.1:9222  로 떠 있는 Chrome 에 붙어라.
+ */
+import { readFileSync, writeFileSync, mkdirSync, existsSync, statSync } from 'node:fs';
+import { join, resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { cropTo45 } from './openai-image-gen.js';
+
+const REPO_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const BASE_W = 1080, BASE_H = 1350, SCALE = 2; // openai-image-gen.js / html-carousel-gen.js 와 동일
+const CHATGPT = 'https://chatgpt.com/';
+const PROFILE = join(REPO_ROOT, '.chrome-profile');
+const DEBUG_URL = 'http://127.0.0.1:9222'; // .mcp.json 이 MCP Chrome 에 열어두는 포트
+
+// 이미지 안에 한글이 들어가므로 정확도 가드를 붙인다 (openai-image-gen.js 의 KOREAN 과 같은 역할).
+const KOREAN = '한글은 오타 없이 정확히 그대로 렌더링할 것. 지정하지 않은 문구는 넣지 말 것.';
+// bg 모드는 글자가 들어가면 트랙의 존재 이유가 무너진다 (한글은 HTML 이 위에 얹는다).
+const NO_TEXT = '글자·숫자·로고·워터마크를 이미지 안에 절대 넣지 마라. 순수한 배경 이미지만. '
+  + '나중에 이 위에 헤드라인을 얹을 수 있게 여백을 넉넉히 두고 차분하게.';
+// 레퍼런스는 **순서대로 1:1 대응이 아니라** 여러 레이아웃 타입의 예시 모음이다.
+// (커버형·본문형·마무리형 등) 슬라이드 성격에 맞는 타입을 고르게 해야 한다.
+const REF_NOTE = '첨부한 이미지들은 디자인 레퍼런스다. '
+  + '배경색·액센트 컬러·타이포그래피·질감 등 전체 톤을 이 이미지들에서 그대로 가져온다. '
+  + '레이아웃은 첨부 순서와 1:1로 대응시키지 마라 — 여러 타입의 예시일 뿐이니, '
+  + '아래에 설명한 장의 성격에 가장 어울리는 타입을 골라 적용해라. '
+  + '문구는 아래에 지정한 것만 쓴다.';
+
+// ChatGPT 는 "9장짜리 캐러셀"이라고 알려주면 한 턴에 여러 장을 알아서 만들어버린다.
+// (실측: 한 턴에 15장) 그러면 다음 프롬프트의 결과로 오인돼 수거가 한 칸씩 밀린다.
+// 그래서 매 메시지마다 "딱 1장" 을 못 박고, 전체 장수는 아예 언급하지 않는다.
+const ONE_ONLY = '이 메시지에 대해 이미지는 **정확히 1장만** 생성해라. '
+  + '여러 장을 한 번에 만들거나 다음 장을 미리 만들지 마라. 다음 장은 내가 따로 요청한다.';
+
+// 비율을 매 메시지에 못 박는다. common_style 에 맡기면 그걸 안 쓴 프롬프트 파일에서
+// 2:3(1003×1568)으로 나오고, cropTo45 의 object-fit:cover 가 위아래 20% 를 잘라
+// 라벨·페이지번호·로고가 날아간다. 잘린 뒤에는 복구가 안 된다.
+const RATIO = '이미지는 반드시 세로 4:5 비율(1080×1350 px)로 만들어라. '
+  + '정사각형이나 2:3 으로 만들지 마라. 중요한 요소는 가장자리에 붙이지 말고 안쪽 여백을 확보해라.';
+
+function parseArgs(argv) {
+  const args = {};
+  for (let i = 2; i < argv.length; i++) {
+    if (!argv[i].startsWith('--')) continue;
+    const key = argv[i].slice(2);
+    args[key] = argv[i + 1] && !argv[i + 1].startsWith('--') ? argv[++i] : true;
+  }
+  return args;
+}
+
+// src 의 file id 만 뽑는다. ts/sig 쿼리는 매 렌더마다 바뀌어서 통째로 비교하면 오탐이 난다.
+// **중복 제거 필수** — ChatGPT 는 이미지 1장을 <img> 3개(본문·라이트박스·숨김)로 그린다.
+// 안 지우면 1장을 3장으로 세서 "여러 장 생성됨" 오탐이 난다.
+const IMG_SEL = 'main img[src*="/backend-api/"]';
+const fileIds = (page) => page.evaluate((sel) =>
+  [...new Set([...document.querySelectorAll(sel)]
+    .map((el) => (/[?&]id=([^&]+)/.exec(el.src) || [])[1])
+    .filter(Boolean))], IMG_SEL);
+
+// **설치된** Chrome 을 찾는다. puppeteer.executablePath() 는 번들 Chrome(구버전, 예: 131)을
+// 돌려주는데, .chrome-profile 은 설치된 Chrome(151)이 만든 것이라 버전이 안 맞으면
+// Chrome 이 포트만 잠깐 열고 바로 죽는다 (connect 시 ECONNRESET).
+function findInstalledChrome() {
+  const cands = [
+    process.env.PROGRAMFILES && join(process.env.PROGRAMFILES, 'Google', 'Chrome', 'Application', 'chrome.exe'),
+    process.env['PROGRAMFILES(X86)'] && join(process.env['PROGRAMFILES(X86)'], 'Google', 'Chrome', 'Application', 'chrome.exe'),
+    process.env.LOCALAPPDATA && join(process.env.LOCALAPPDATA, 'Google', 'Chrome', 'Application', 'chrome.exe'),
+    '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+    '/usr/bin/google-chrome',
+  ].filter(Boolean);
+  return cands.find((p) => existsSync(p)) || null;
+}
+
+// Chrome 을 **부모와 분리해서** 띄운다.
+// puppeteer.launch 로 띄우면 이 스크립트가 끝나는 순간 puppeteer 의 process.on('exit')
+// 훅이 브라우저를 같이 죽인다 (handleSIGTERM 등으로는 못 막는다). 그러면 Bash 툴 타임아웃에
+// 잘릴 때마다 9장을 다 못 만든 채 창이 닫히고, 다음 실행이 이어받을 창도 없다.
+// detached + unref 로 띄우고 CDP 로 붙으면, 이 프로세스가 죽어도 창은 남는다.
+async function spawnDetachedChrome(exe) {
+  const { spawn } = await import('node:child_process');
+  const port = new URL(DEBUG_URL).port;
+  spawn(exe, [
+    `--remote-debugging-port=${port}`,
+    `--user-data-dir=${PROFILE}`,
+    '--no-first-run',
+    '--no-default-browser-check',
+  ], { detached: true, stdio: 'ignore' }).unref();
+
+  for (let i = 0; i < 60; i++) { // 최대 30초 대기
+    try {
+      const res = await fetch(`${DEBUG_URL}/json/version`);
+      if (res.ok) return;
+    } catch { /* 아직 안 떴다 */ }
+    await new Promise((r) => setTimeout(r, 500));
+  }
+  throw new Error(`Chrome 이 30초 안에 ${DEBUG_URL} 를 열지 못했습니다`);
+}
+
+async function waitForComposer(page) {
+  await page.waitForSelector('#prompt-textarea', { timeout: 60_000 });
+  // 로그인이 풀렸으면 여기서 프롬프트 창이 안 뜬다 — 위 waitForSelector 가 던진다.
+}
+
+async function attachRef(page, refPaths) {
+  const input = await page.waitForSelector('input[type="file"]', { timeout: 30_000 });
+  await input.uploadFile(...refPaths); // 여러 장을 한 번에 올린다
+  // 업로드가 끝나기 전에 Enter 를 치면 첨부 없이 전송된다. 썸네일이 붙을 때까지 기다린다.
+  await page.waitForFunction(
+    () => !!document.querySelector('form img, form [data-testid*="attachment"]'),
+    { timeout: 120_000 },
+  ).catch(() => console.warn('  (경고) 첨부 썸네일을 확인하지 못했습니다. 그대로 진행합니다.'));
+}
+
+async function sendPrompt(page, text) {
+  await page.click('#prompt-textarea');
+  // 프롬프트는 항상 한 줄로 만든다 — 개행이 들어가면 Enter 가 도중에 전송해버린다.
+  await page.type('#prompt-textarea', text.replace(/\s*\n\s*/g, ' '));
+  await page.keyboard.press('Enter');
+}
+
+// 새 이미지를 기다렸다가 **이 프롬프트에 해당하는 1장**을 골라 돌려준다.
+//
+// 첫 장이 보이자마자 집고 넘어가면 안 된다. ChatGPT 가 한 턴에 여러 장을 만들면
+// 나머지가 다음 프롬프트의 결과로 오인돼 수거가 한 칸씩 밀린다 (실제로 그렇게 밀렸다).
+// 새 이미지가 보인 뒤에도 개수가 멈출 때까지 기다렸다가, **가장 먼저 나온 것**을 쓴다.
+// 여러 장이 나왔으면 경고를 남긴다 — 프롬프트가 다장 생성을 유도했다는 신호다.
+const SETTLE_MS = 12_000; // 개수가 이만큼 안 늘면 그 턴은 끝난 것으로 본다
+
+async function waitForNewImage(page, before, timeoutMs) {
+  const deadline = Date.now() + timeoutMs;
+  let fresh = [], lastChange = 0;
+  while (Date.now() < deadline) {
+    const now = (await fileIds(page)).filter((id) => !before.includes(id));
+    if (now.length !== fresh.length) { fresh = now; lastChange = Date.now(); }
+    else if (fresh.length && Date.now() - lastChange >= SETTLE_MS) {
+      if (fresh.length > 1) {
+        console.warn(`  (경고) 한 프롬프트에 ${fresh.length}장이 생성됨 — 첫 장만 사용합니다.`);
+      }
+      return fresh[0];
+    }
+    await new Promise((r) => setTimeout(r, 3000));
+  }
+  if (fresh.length) return fresh[0]; // 타임아웃이어도 받은 게 있으면 쓴다
+  throw new Error(`이미지가 ${Math.round(timeoutMs / 1000)}초 안에 안 나옴`);
+}
+
+// PNG 헤더(IHDR)에서 크기만 읽는다. 디코딩 라이브러리 없이 바이트만 본다.
+const pngSize = (buf) => ({ w: buf.readUInt32BE(16), h: buf.readUInt32BE(20) });
+
+// cropTo45 는 object-fit:cover 라 원본이 4:5 가 아니면 **위아래(또는 좌우)를 잘라낸다.**
+// ChatGPT 가 2:3(1024×1536)으로 주면 17% 가량이 잘려 라벨·로고가 날아간다.
+// 잘리는지 여부는 눈으로만 알 수 있으니 여기서 수치로 남긴다.
+const TARGET_RATIO = BASE_W / BASE_H; // 0.8
+function checkRatio(buf) {
+  const { w, h } = pngSize(buf);
+  const r = w / h;
+  const off = Math.abs(r - TARGET_RATIO) / TARGET_RATIO;
+  return { w, h, r, warn: off > 0.02 ? Math.round(off * 100) : 0 };
+}
+
+// 페이지 안에서 fetch 한다 — 인증 쿠키가 이미 붙어 있어 별도 토큰이 필요 없다.
+// Chrome 의 다운로드 정책(연속 다운로드 차단)도 피한다.
+async function downloadImage(page, fileId) {
+  const b64 = await page.evaluate(async (sel, id) => {
+    const el = [...document.querySelectorAll(sel)].find((e) => e.src.includes(`id=${id}`));
+    if (!el) return null;
+    const buf = new Uint8Array(await (await fetch(el.src)).arrayBuffer());
+    let s = '';
+    for (let i = 0; i < buf.length; i += 8192) s += String.fromCharCode(...buf.subarray(i, i + 8192));
+    return btoa(s);
+  }, IMG_SEL, fileId);
+  if (!b64) throw new Error('이미지를 받아오지 못함');
+  return Buffer.from(b64, 'base64');
+}
+
+async function main() {
+  const args = parseArgs(process.argv);
+  const topic = args.topic || 'default';
+  const mode = args.mode === 'bg' ? 'bg' : 'slide';
+  const only = args.only ? Number(args.only) : null;
+  const dryRun = !!args['dry-run'];
+  const timeoutMs = (Number(args.timeout) || 300) * 1000;
+  // --ref 는 콤마로 여러 장을 받는다. 전부 첫 장에 첨부해 "타입 예시 모음"으로 준다.
+  const refPaths = args.ref
+    ? String(args.ref).split(',').map((p) => resolve(REPO_ROOT, p.trim())).filter(Boolean)
+    : [];
+
+  // 로고는 모델이 그리게 하지 않는다 — 매번 뭉개진다. 자리만 비우게 하고 크롭할 때 원본을 얹는다.
+  const logoPos = args['logo-pos'] ? String(args['logo-pos']) : '';
+  let logo = null;
+  if (args.logo && logoPos && logoPos !== '넣지 않음') {
+    const lp = resolve(REPO_ROOT, String(args.logo));
+    if (!existsSync(lp)) { console.error(`[ERROR] 로고 파일 없음: ${lp}`); process.exit(1); }
+    logo = { svg: readFileSync(lp), pos: logoPos };
+  }
+
+  const slidesPath = args.slides
+    ? resolve(args.slides)
+    : join(REPO_ROOT, 'templates', mode === 'slide' ? 'slides.example.json' : 'backgrounds.example.json');
+  if (!existsSync(slidesPath)) {
+    console.error(`[ERROR] 프롬프트 파일 없음: ${slidesPath}`);
+    process.exit(1);
+  }
+  for (const p of refPaths) {
+    if (!existsSync(p)) { console.error(`[ERROR] 레퍼런스 이미지 없음: ${p}`); process.exit(1); }
+  }
+
+  const data = JSON.parse(readFileSync(slidesPath, 'utf8'));
+  const commonStyle = data.common_style || '';
+  let slides = data.slides || [];
+  if (!slides.length) { console.error('[ERROR] slides 배열이 비어 있습니다.'); process.exit(1); }
+  if (only != null) {
+    slides = slides.filter((s) => s.n === only);
+    if (!slides.length) { console.error(`[ERROR] n=${only} 슬라이드 없음`); process.exit(1); }
+  }
+
+  // 첫 장만 스타일 전체를 싣는다. 이후는 같은 대화 안이라 "같은 스타일로" 로 이어받는다
+  // — 매번 스타일을 반복하면 오히려 해석이 흔들려 9장 톤이 갈린다.
+  // 로고는 크롭할 때 원본 SVG 로 합성한다. 모델에게는 그 자리를 비우라고 해야 겹치지 않는다.
+  const logoNote = logo
+    ? `이미지 안에 로고·워드마크·브랜드명을 절대 그리지 마라. ${logo.pos} 영역은 비워두고 여백으로 남겨라 (나중에 실제 로고를 얹는다).`
+    : '';
+  const guard = mode === 'slide' ? KOREAN : NO_TEXT;
+  // first = 이 실행에서 처음 보내는 장. 인덱스가 아니라 실제 전송 여부로 판단해야 한다 —
+  // 스킵/--only 로 1번이 빠지면 새 대화에 스타일이 하나도 안 실린 채 시작된다.
+  const build = (s, first) => (first
+    ? [refPaths.length ? REF_NOTE : '', commonStyle, s.prompt, guard, logoNote, RATIO, ONE_ONLY]
+    : ['같은 스타일로 다음 장.', s.prompt, guard, logoNote, RATIO, ONE_ONLY]
+  ).filter(Boolean).join(' ');
+
+  const outDir = mode === 'slide'
+    ? join(REPO_ROOT, 'output', topic)
+    : join(REPO_ROOT, 'output', topic, 'bg');
+  const name = (n) => `${mode === 'slide' ? 'slide' : 'bg'}-${String(n).padStart(2, '0')}.png`;
+
+  if (dryRun) {
+    console.log(`[DRY RUN] mode=${mode} · ${slides.length}장 · 출력: ${outDir}`);
+    console.log(`          레퍼런스: ${refPaths.join(", ") || '(없음)'}`);
+    if (mode === 'slide') console.log(`          생성 후 ${BASE_W}×${BASE_H} 의 ${SCALE}배로 크롭\n`);
+    else console.log('          배경은 원본 비율 그대로 저장 (HTML 이 cover 로 채운다)\n');
+    slides.forEach((s, i) => {
+      console.log(`--- ${name(s.n)} (${s.role || '?'}) ---`);
+      console.log(build(s, i === 0) + '\n');
+    });
+    return;
+  }
+
+  mkdirSync(outDir, { recursive: true });
+  const { default: puppeteer } = await import('puppeteer');
+
+  // 크롭 전용 헤드리스 브라우저. ChatGPT 창과 섞으면 그 페이지를 오염시킨다.
+  // bg 모드는 원본 비율 그대로 두므로 띄우지 않는다.
+  let cropper = null, cropPage = null;
+  if (mode === 'slide') {
+    cropper = await puppeteer.launch({ headless: 'new', args: ['--no-sandbox', '--disable-setuid-sandbox'] });
+    cropPage = await cropper.newPage();
+    await cropPage.setViewport({ width: BASE_W, height: BASE_H, deviceScaleFactor: SCALE });
+  }
+
+  // 프로필은 Chrome 한 개만 잠글 수 있다. chrome-devtools MCP 가 이미 그 프로필로 떠 있는 게
+  // 흔한 상황이라, 먼저 붙어보고(attach) 안 되면 그때 직접 띄운다. 순서를 바꾸면 늘 잠김 에러가 난다.
+  const url = String(args['browser-url'] || DEBUG_URL);
+  let browser = null;
+  try {
+    browser = await puppeteer.connect({ browserURL: url, defaultViewport: null, protocolTimeout: 600_000 });
+    console.log(`(떠 있는 Chrome 에 붙었습니다: ${url})`);
+  } catch {
+    if (args['browser-url']) {
+      await cropper?.close();
+      console.error(`[ERROR] ${url} 에 Chrome 이 없습니다.`);
+      process.exit(1);
+    }
+  }
+  if (!browser) {
+    const exe = args['chrome-path'] ? String(args['chrome-path']) : findInstalledChrome();
+    if (!exe) {
+      await cropper?.close();
+      console.error('[ERROR] 설치된 Chrome 을 찾지 못했습니다. --chrome-path 로 지정하세요.');
+      process.exit(1);
+    }
+    try {
+      await spawnDetachedChrome(exe);
+      browser = await puppeteer.connect({ browserURL: DEBUG_URL, defaultViewport: null, protocolTimeout: 600_000 });
+      console.log(`(Chrome 을 새로 띄웠습니다: ${DEBUG_URL})`);
+    } catch (e) {
+      await cropper?.close();
+      console.error(`[ERROR] Chrome 을 열지 못했습니다: ${e.message}`);
+      console.error(`        같은 프로필(${PROFILE})로 포트 없이 뜬 Chrome 이 있으면 그 창을 닫으세요.`);
+      process.exit(1);
+    }
+  }
+
+  console.log(`\n${slides.length}장 생성 (ChatGPT 웹 · ${refPaths.length ? refPaths.length + '장 첨부' : '레퍼런스 없음'})`);
+  console.log('⚠️  한글이 이미지 안에 들어갑니다. 생성 후 전부 눈으로 확인하세요.\n');
+
+  const summary = [];
+  let primed = false; // 이 실행에서 스타일/레퍼런스를 실은 첫 장을 이미 보냈는가
+  const page = await browser.newPage();
+  try {
+    await page.goto(CHATGPT, { waitUntil: 'domcontentloaded', timeout: 120_000 });
+    await waitForComposer(page);
+
+    for (let i = 0; i < slides.length; i++) {
+      const s = slides[i];
+      const outPathEarly = join(outDir, name(s.n));
+      // 이미 있는 장은 건너뛴다. 호출자의 타임아웃에 잘려도 다시 부르면 이어서 돈다.
+      // (--force 로 무시하고 전부 다시 뽑을 수 있다.)
+      if (!args.force && existsSync(outPathEarly)) {
+        console.log(`[${s.n}/${slides.length}] ${s.role || '?'} ... SKIP (이미 있음)`);
+        summary.push([name(s.n), 'SKIP', '-', '기존 파일 유지']);
+        continue;
+      }
+      process.stdout.write(`[${s.n}/${slides.length}] ${s.role || '?'} ... `);
+      const t0 = Date.now();
+      const first = !primed;
+      try {
+        if (first && refPaths.length) await attachRef(page, refPaths);
+        // 보낸 뒤에 스냅샷을 뜨면 이미 생성된 장을 새 것으로 착각한다. 반드시 전송 전에.
+        let before = await fileIds(page);
+        await sendPrompt(page, build(s, first));
+        primed = true;
+        // 첨부한 레퍼런스는 **전송된 뒤에야** main 안에 /backend-api/ 이미지로 나타난다.
+        // 위 스냅샷에는 안 잡히므로 그대로 두면 생성 결과로 오인돼 1장이 밀리고 이후 전부
+        // 한 칸씩 어긋난다. 썸네일이 다 뜰 때까지 기다렸다가 before 를 다시 뜬다
+        // (이미지 생성은 25초 이상 걸리므로 그 사이에 결과가 끼어들 일은 없다).
+        if (first && refPaths.length) {
+          await page.waitForFunction(
+            (sel, n) => document.querySelectorAll(sel).length >= n,
+            { timeout: 60_000 }, IMG_SEL, before.length + refPaths.length,
+          ).catch(() => console.warn('\n  (경고) 레퍼런스 썸네일을 확인하지 못했습니다.'));
+          before = await fileIds(page);
+        }
+        const fileId = await waitForNewImage(page, before, timeoutMs);
+        let buf = await downloadImage(page, fileId);
+        const src = checkRatio(buf);
+        if (mode === 'slide') buf = await cropTo45(buf, cropPage, logo);
+        const outPath = join(outDir, name(s.n));
+        writeFileSync(outPath, buf);
+        const kb = Math.round(statSync(outPath).size / 1024);
+        const dt = ((Date.now() - t0) / 1000).toFixed(1);
+        const ratio = `원본 ${src.w}×${src.h}`
+          + (src.warn ? ` ⚠️ 4:5 에서 ${src.warn}% 벗어남 → cover 로 잘림` : ' (4:5)');
+        console.log(`OK (${dt}s, ${kb}KB, ${ratio}) -> ${name(s.n)}`);
+        summary.push([name(s.n), 'OK', `${dt}s`, `${kb}KB · ${src.w}×${src.h}${src.warn ? ' ⚠️' : ''}`]);
+      } catch (e) {
+        const dt = ((Date.now() - t0) / 1000).toFixed(1);
+        console.log(`ERR (${dt}s): ${e.message}`);
+        summary.push([name(s.n), 'ERR', `${dt}s`, e.message.slice(0, 60)]);
+      }
+    }
+  } finally {
+    await cropper?.close(); // 크롭용 헤드리스는 이 실행 전용이라 닫아도 된다
+    // ChatGPT 창은 **닫지 않는다.** 붙어서 쓴 거면 남의 창이고, 직접 띄운 거라도
+    // 9장을 다 못 채웠으면 다음 실행이 이어서 써야 한다. 떼기만 한다.
+    browser.disconnect();
+  }
+
+  console.log('\n=== SUMMARY ===');
+  summary.forEach(([f, st, dt, info]) => console.log(`  ${f.padEnd(12)} ${st.padEnd(5)} ${dt.padStart(7)}  ${info}`));
+  const missing = summary.filter(([, st]) => st === 'ERR').length;
+  console.log(`\n출력: ${outDir}`);
+  console.log(missing
+    ? `Chrome 창은 열어둡니다 (${missing}장 남음). 같은 명령을 다시 부르면 그 창에 붙어 이어서 뽑습니다.`
+    : 'Chrome 창은 열어둡니다. 다음 실행이 같은 창에 붙습니다.');
+  if (mode === 'slide') {
+    console.log(`검사: node scripts/quality-check.js --dir output/${topic}`);
+    console.log('※ 한글 오타는 스크립트가 못 잡습니다. 반드시 눈으로 확인하세요.');
+  } else {
+    console.log('다음: carousel-html-writer 가 이 배경을 참조해 슬라이드 HTML 을 작성 →');
+    console.log(`      node scripts/html-carousel-gen.js --topic ${topic}`);
+  }
+
+  if (summary.some(([, st]) => st === 'ERR')) process.exit(1);
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) main().catch((e) => { console.error('ERROR:', e); process.exit(1); });

package/scripts/hook-post-write.js

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+/**
+ * PostToolUse 훅 — Write/Edit 후 자동 품질 검사.
+ *
+ * 설정: .claude/settings.json 의 hooks.PostToolUse 에 등록.
+ *
+ * 동작:
+ *   - templates/slides.*.json 저장 시 → quality-check.js --prompt <파일> 자동 실행
+ *   - output/*/slide-*.png 저장 시 → 같은 폴더에 대해 quality-check.js --dir 자동 실행
+ *
+ * stdin 으로 PostToolUse payload 받음 (Claude Code 훅 규약).
+ */
+import { spawnSync } from 'node:child_process';
+import { dirname, basename, join } from 'node:path';
+
+function readStdin() {
+  try {
+    return require('node:fs').readFileSync(0, 'utf-8');
+  } catch {
+    return '';
+  }
+}
+
+function run(script, args) {
+  const r = spawnSync('node', [script, ...args], { encoding: 'utf-8' });
+  process.stdout.write(r.stdout || '');
+  process.stderr.write(r.stderr || '');
+  return r.status;
+}
+
+function main() {
+  const raw = readStdin();
+  let payload = {};
+  try {
+    payload = JSON.parse(raw);
+  } catch {}
+
+  const toolInput = payload.tool_input || {};
+  const filePath = toolInput.file_path || '';
+  if (!filePath) return;
+
+  const fname = basename(filePath);
+  const dir = dirname(filePath);
+
+  // 1) 프롬프트 JSON 저장 시
+  if (/^slides\..+\.json$/.test(fname) || fname === 'slides.example.json') {
+    console.log(`\n[hook] 프롬프트 JSON 감지 → 스키마 검증`);
+    run(join('scripts', 'quality-check.js'), ['--prompt', filePath]);
+    return;
+  }
+
+  // 2) 슬라이드 PNG 저장 시 — 마지막 장(slide-09)일 때만 폴더 전체 검증
+  if (/^slide-09\.png$/.test(fname)) {
+    console.log(`\n[hook] slide-09 감지 → 폴더 전체 검증`);
+    run(join('scripts', 'quality-check.js'), ['--dir', dir]);
+    return;
+  }
+}
+
+main();

package/scripts/html-carousel-gen.js

@@ -0,0 +1,125 @@
+#!/usr/bin/env node
+/**
+ * insta-carousel-builder — HTML/Puppeteer 캐러셀 생성기
+ *
+ * slides 폴더의 *.html 파일을 1080×1350 (2x 레티나) PNG로 일괄 캡처.
+ * 한글 100% 정확, 비용 0원, 결정적 결과.
+ *
+ * 사용법:
+ *   # 1. templates/html-templates/ 또는 docs/sample-html/ 의 HTML 9장을 복사
+ *   #    output/{topic}/slides/ 에 두기 (또는 직접 작성)
+ *   # 2. 실행:
+ *   node scripts/html-carousel-gen.js --topic my-topic
+ *
+ *   # 단일 슬라이드만 캡처:
+ *   node scripts/html-carousel-gen.js --topic my-topic --only 3
+ *
+ * 의존성:
+ *   npm install puppeteer
+ *
+ * 폰트:
+ *   Pretendard 시스템 설치 권장 (없으면 CDN으로 폴백되지만 첫 로드 느림)
+ *   Linux: https://github.com/orioncactus/pretendard 릴리즈 참조
+ */
+import puppeteer from 'puppeteer';
+import { readdirSync, existsSync, mkdirSync } from 'node:fs';
+import { join, resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const REPO_ROOT = resolve(__dirname, '..');
+
+function parseArgs(argv) {
+  const args = {};
+  for (let i = 2; i < argv.length; i++) {
+    if (argv[i].startsWith('--') && argv[i + 1]) {
+      args[argv[i].slice(2)] = argv[++i];
+    }
+  }
+  return args;
+}
+
+const CONFIG = {
+  width: 1080,
+  height: 1350,
+  deviceScaleFactor: 2,
+};
+
+async function captureSlides({ slidesDir, outputDir, only }) {
+  if (!existsSync(outputDir)) mkdirSync(outputDir, { recursive: true });
+
+  let files = readdirSync(slidesDir)
+    .filter((f) => f.endsWith('.html'))
+    .sort();
+
+  if (only) {
+    const target = `slide-${String(only).padStart(2, '0')}.html`;
+    files = files.filter((f) => f === target);
+    if (files.length === 0) {
+      console.error(`❌ ${target} 없음 in ${slidesDir}`);
+      process.exit(1);
+    }
+  }
+
+  if (files.length === 0) {
+    console.error(`❌ ${slidesDir} 에 HTML 파일이 없습니다.`);
+    process.exit(1);
+  }
+
+  console.log(`\n${files.length}개 슬라이드 캡처 시작 (${slidesDir})\n`);
+
+  const browser = await puppeteer.launch({
+    headless: 'new',
+    args: ['--no-sandbox', '--disable-setuid-sandbox', '--font-render-hinting=none'],
+  });
+
+  const page = await browser.newPage();
+  await page.setViewport({
+    width: CONFIG.width,
+    height: CONFIG.height,
+    deviceScaleFactor: CONFIG.deviceScaleFactor,
+  });
+
+  for (const file of files) {
+    const filePath = resolve(slidesDir, file);
+    const fileUrl = 'file:///' + filePath.replace(/\\/g, '/');
+    const outName = file.replace('.html', '.png');
+    const outPath = join(outputDir, outName);
+
+    await page.goto(fileUrl, { waitUntil: 'networkidle0', timeout: 15000 });
+    await page.evaluate(() => document.fonts.ready);
+    await new Promise((r) => setTimeout(r, 500));
+
+    await page.screenshot({
+      path: outPath,
+      type: 'png',
+      clip: { x: 0, y: 0, width: CONFIG.width, height: CONFIG.height },
+    });
+
+    console.log(`  ✓ ${outName}`);
+  }
+
+  await browser.close();
+  console.log(`\n완료! ${outputDir}\n`);
+}
+
+async function main() {
+  const args = parseArgs(process.argv);
+  const topic = args.topic || 'default';
+  const slidesDir = args['slides-dir'] || join(REPO_ROOT, 'output', topic, 'slides');
+  const outputDir = join(REPO_ROOT, 'output', topic);
+
+  if (!existsSync(slidesDir)) {
+    console.error(`❌ slides 폴더 없음: ${slidesDir}`);
+    console.error('   docs/sample-html/ 의 9장을 복사하거나, 직접 HTML 작성 후 실행하세요.');
+    process.exit(1);
+  }
+
+  await captureSlides({ slidesDir, outputDir, only: args.only });
+}
+
+main().catch((e) => {
+  console.error('ERROR:', e);
+  process.exit(1);
+});