sns-auto-builder 1.0.0

package/scripts/nanobanana-gen.py

@@ -0,0 +1,137 @@
+"""
+insta-carousel-builder — 나노바나나 Pro(Gemini 3.0 Pro Image) 인스타 캐러셀 생성기
+
+사용법:
+    # 1. .env 에 GEMINI_API_KEY=... 추가 (.env.example 참고)
+    # 2. slides.json 에 9장 프롬프트 수정 (또는 기본 예제 그대로 사용)
+    # 3. 실행:
+    python scripts/nanobanana-gen.py --topic my-topic
+
+결과:
+    output/{topic}/slide-01.png ~ slide-09.png
+
+참고:
+    - 모델: gemini-3-pro-image-preview (별칭 nano-banana-pro-preview)
+    - 한글 정확도 실측: 97.8% (에이나우 2026-04-15 9장 테스트 기준)
+    - 1장당 약 25초 / 9장 약 4분 / 비용 약 500~1000원
+"""
+from __future__ import annotations
+
+import argparse
+import base64
+import json
+import os
+import sys
+import time
+from pathlib import Path
+
+try:
+    from dotenv import load_dotenv
+    from google import genai
+    from google.genai import types
+except ImportError as e:
+    print(f"[ERROR] 의존성 누락: {e}")
+    print("        pip install python-dotenv google-genai")
+    sys.exit(1)
+
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+DEFAULT_SLIDES_JSON = REPO_ROOT / "templates" / "slides.example.json"
+
+
+def load_slides(slides_path: Path) -> list[dict]:
+    if not slides_path.exists():
+        print(f"[ERROR] slides 파일 없음: {slides_path}")
+        print(f"        templates/slides.example.json 을 복사해서 수정하세요.")
+        sys.exit(1)
+    with slides_path.open("r", encoding="utf-8") as f:
+        data = json.load(f)
+    slides = data.get("slides", [])
+    if len(slides) != 9:
+        print(f"[WARN] 슬라이드 개수 {len(slides)} (권장: 9장 — 인스타 캐러셀 최대)")
+    return slides
+
+
+def render_prompt(slide: dict, common_style: str) -> str:
+    return f"{common_style}\n\n{slide['prompt']}"
+
+
+def main():
+    ap = argparse.ArgumentParser(description="나노바나나 Pro 인스타 캐러셀 생성기")
+    ap.add_argument("--topic", default="default", help="출력 폴더명. output/{topic}/ 에 저장")
+    ap.add_argument("--slides", default=str(DEFAULT_SLIDES_JSON), help="slides.json 경로")
+    ap.add_argument("--model", default="gemini-3-pro-image-preview", help="Gemini 이미지 모델 ID")
+    ap.add_argument("--dry-run", action="store_true", help="API 호출 없이 프롬프트만 출력")
+    args = ap.parse_args()
+
+    try:
+        sys.stdout.reconfigure(encoding="utf-8")
+    except Exception:
+        pass
+
+    load_dotenv(REPO_ROOT / ".env")
+    api_key = os.getenv("GEMINI_API_KEY")
+    if not api_key and not args.dry_run:
+        print("[ERROR] GEMINI_API_KEY not found in .env or environment.")
+        print("        .env.example 을 복사해서 .env 를 만들고 키를 추가하세요.")
+        print("        키 발급: https://aistudio.google.com/apikey")
+        sys.exit(1)
+
+    slides_path = Path(args.slides)
+    data = json.loads(slides_path.read_text(encoding="utf-8"))
+    common_style = data.get("common_style", "")
+    slides = data.get("slides", [])
+
+    out_dir = REPO_ROOT / "output" / args.topic
+    out_dir.mkdir(parents=True, exist_ok=True)
+
+    if args.dry_run:
+        print(f"[DRY RUN] {len(slides)} slides, output: {out_dir}")
+        for slide in slides:
+            print(f"\n--- slide-{slide['n']:02d} ({slide.get('role','?')}) ---")
+            print(render_prompt(slide, common_style)[:500])
+        return
+
+    client = genai.Client(api_key=api_key)
+    summary = []
+
+    for slide in slides:
+        n = slide["n"]
+        out_path = out_dir / f"slide-{n:02d}.png"
+        prompt = render_prompt(slide, common_style)
+
+        print(f"[{n}/{len(slides)}] generating {slide.get('role','?')}...", end=" ", flush=True)
+        t0 = time.time()
+        try:
+            resp = client.models.generate_content(model=args.model, contents=[prompt])
+            image_saved = False
+            for part in resp.candidates[0].content.parts:
+                if getattr(part, "inline_data", None) and part.inline_data.data:
+                    blob = part.inline_data.data
+                    if isinstance(blob, str):
+                        blob = base64.b64decode(blob)
+                    with open(out_path, "wb") as f:
+                        f.write(blob)
+                    image_saved = True
+                    break
+            dt = time.time() - t0
+            if image_saved:
+                kb = out_path.stat().st_size / 1024
+                print(f"OK ({dt:.1f}s, {kb:.0f}KB) -> {out_path.name}")
+                summary.append((n, "OK", f"{dt:.1f}s", f"{kb:.0f}KB"))
+            else:
+                print(f"FAIL ({dt:.1f}s, no image in response)")
+                summary.append((n, "FAIL_NO_IMG", f"{dt:.1f}s", "-"))
+        except Exception as e:
+            dt = time.time() - t0
+            print(f"ERR ({dt:.1f}s): {e}")
+            summary.append((n, "ERR", f"{dt:.1f}s", str(e)[:60]))
+
+    print("\n=== SUMMARY ===")
+    for n, status, dt, info in summary:
+        print(f"  slide-{n:02d}  {status:12}  {dt:>7}  {info}")
+    print(f"\nOutput: {out_dir}")
+
+
+if __name__ == "__main__":
+    main()

package/scripts/openai-image-gen.js

@@ -0,0 +1,230 @@
+#!/usr/bin/env node
+/**
+ * sns-auto-builder — OpenAI 이미지 생성기 (배경 / 슬라이드 전체)
+ *
+ * 원본 레포에 없는 추가분입니다. `scripts/nanobanana-gen.py` 는 손대지 않았습니다.
+ * 그 스크립트의 CLI/JSON 스키마를 미러링한 형제입니다.
+ * (Python 이 이 환경에 없어 Node 로 작성. 의존성은 캡처용 puppeteer 하나뿐 — 이미 설치돼 있음.)
+ *
+ * ── 두 가지 모드 ──────────────────────────────────────
+ * --mode bg    (기본) 글자 **없는 배경**만. 한글은 HTML 이 위에 얹는다 → 한글 100% 정확
+ *              출력: output/{topic}/bg/bg-NN.png (원본 비율 그대로, HTML 이 cover 로 채움)
+ *
+ * --mode slide       슬라이드 **완성본**. 한글이 이미지 안에 들어간다 → 비결정적, 육안 검수 필수
+ *              출력: output/{topic}/slide-NN.png (1080×1350 의 2배 = 2160×2700 로 크롭)
+ *
+ * ⚠️ slide 모드 경고
+ *   AI 이미지 모델의 한글은 매번 달라진다. 원본 레포가 Gemini 로 실측한 값이 97.8%
+ *   (9장당 1~2글자 오타)이고, OpenAI 의 한글 정확도는 그보다 낮을 수 있다.
+ *   **생성 후 9장 전부 눈으로 확인해라.** 글자가 중요한 콘텐츠면 bg 모드 + HTML 을 써라.
+ *
+ * 해상도 처리
+ *   OpenAI 는 4:5(1080×1350)를 직접 지원하지 않는다. 세로는 1024×1536(2:3)이 가장 가깝다.
+ *   slide 모드는 받은 이미지를 puppeteer 로 1080×1350 캔버스에 cover 로 깔아 2x 캡처한다.
+ *   → quality-check.js --dir 의 "1080×1350 정수배" 검사를 통과하고 HTML 트랙과 배율이 같아진다.
+ *   위아래가 잘리므로 프롬프트에서 중요한 요소를 가장자리로 몰지 마라.
+ *
+ * 사용법:
+ *   node scripts/openai-image-gen.js --topic my-topic --slides templates/backgrounds.my-topic.json
+ *   node scripts/openai-image-gen.js --topic my-topic --slides templates/slides.my-topic.json --mode slide
+ *   node scripts/openai-image-gen.js --topic my-topic --dry-run
+ *   node scripts/openai-image-gen.js --topic my-topic --only 3
+ */
+import { readFileSync, writeFileSync, mkdirSync, existsSync, statSync } from 'node:fs';
+import { join, resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const REPO_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const API = 'https://api.openai.com/v1/images/generations';
+const BASE_W = 1080, BASE_H = 1350, SCALE = 2; // html-carousel-gen.js 와 동일
+
+// 배경에 글자가 들어가면 한글이 깨진다. 그게 bg 트랙을 쓰는 이유 자체를 무너뜨린다.
+const NO_TEXT = 'Absolutely no text, no letters, no words, no numbers, no logos, no watermarks, '
+  + 'no UI elements anywhere in the image. Pure imagery only. '
+  + 'Leave the composition calm and uncluttered so headline text can be overlaid on top later.';
+
+// slide 모드에서는 한글을 이미지가 직접 그린다. 정확도를 최대한 끌어올린다.
+const KOREAN = 'Render every Korean character exactly as written, with correct jamo composition. '
+  + 'Do not invent, translate, substitute, or stylize any character. '
+  + 'Do not add any text that is not explicitly specified. '
+  + 'Vertical 4:5 composition; keep all text well inside the frame with generous margins, '
+  + 'because the top and bottom edges will be cropped.';
+
+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;
+}
+
+// dotenv 없이 .env 를 읽는다. 이미 설정된 환경변수는 덮어쓰지 않는다.
+function loadEnv(file) {
+  if (!existsSync(file)) return;
+  for (const line of readFileSync(file, 'utf8').split(/\r?\n/)) {
+    const m = /^\s*([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$/.exec(line);
+    if (m && !process.env[m[1]]) process.env[m[1]] = m[2].trim().replace(/^["']|["']$/g, '');
+  }
+}
+
+async function generateOne({ prompt, model, size, quality, apiKey }) {
+  const res = await fetch(API, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json', authorization: `Bearer ${apiKey}` },
+    body: JSON.stringify({ model, prompt, size, quality, n: 1 }),
+  });
+  const text = await res.text();
+  let body;
+  try { body = JSON.parse(text); } catch { throw new Error(`응답이 JSON 이 아님 (HTTP ${res.status}): ${text.slice(0, 200)}`); }
+  if (!res.ok) throw new Error(body?.error?.message || `HTTP ${res.status}`);
+  const item = body?.data?.[0];
+  if (item?.b64_json) return Buffer.from(item.b64_json, 'base64');
+  if (item?.url) return Buffer.from(await (await fetch(item.url)).arrayBuffer()); // url 로 오는 모델 대비
+  throw new Error('응답에 이미지가 없음');
+}
+
+// 워드마크 위치 → CSS. 브랜드 설정의 선택지와 문자열이 같아야 한다.
+const LOGO_POS = {
+  '하단 중앙': 'bottom:4.5%;left:50%;transform:translateX(-50%)',
+  '하단 좌측': 'bottom:4.5%;left:8%',
+  '하단 우측': 'bottom:4.5%;right:8%',
+  '상단 좌측': 'top:5%;left:8%',
+};
+
+// OpenAI 비율(2:3)을 인스타 4:5 로 맞춘다. 새 의존성 없이 이미 있는 puppeteer 로 처리.
+//
+// logo 를 주면 크롭하면서 **진짜 로고를 얹는다.** 이미지 모델에게 로고를 그리게 하면
+// 매번 뭉개지므로, 모델에겐 자리만 비우게 하고 원본 SVG 를 여기서 합성한다.
+export async function cropTo45(buf, page, logo = null) {
+  const dataUrl = `data:image/png;base64,${buf.toString('base64')}`;
+  const pos = logo && LOGO_POS[logo.pos];
+  const mark = pos
+    ? `<img src="data:image/svg+xml;base64,${logo.svg.toString('base64')}"
+            style="position:absolute;${pos};height:3.4%;max-width:34%;object-fit:contain">`
+    : '';
+  await page.setContent(
+    `<body style="margin:0;width:${BASE_W}px;height:${BASE_H}px;overflow:hidden;background:#000;position:relative">
+       <img src="${dataUrl}" style="width:100%;height:100%;object-fit:cover;display:block">
+       ${mark}
+     </body>`,
+    { waitUntil: 'load' });
+  await page.evaluate(() => Promise.all(Array.from(document.images, (i) => i.decode().catch(() => {}))));
+  // 최신 puppeteer 는 Uint8Array 를 준다. 이후 처리를 위해 Buffer 로 맞춘다.
+  return Buffer.from(await page.screenshot({ type: "png", clip: { x: 0, y: 0, width: BASE_W, height: BASE_H } }));
+}
+
+async function main() {
+  const args = parseArgs(process.argv);
+  const topic = args.topic || 'default';
+  const mode = args.mode === 'slide' ? 'slide' : 'bg';
+  const model = args.model || 'gpt-image-2'; // --model 로 교체 가능 (gpt-image-1, -1-mini, -1.5 등)
+  const size = args.size || '1024x1536';
+  const quality = args.quality || 'high';
+  const dryRun = !!args['dry-run'];
+
+  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}`);
+    console.error('        templates/ 의 예제를 복사해서 수정하세요.');
+    process.exit(1);
+  }
+
+  loadEnv(join(REPO_ROOT, '.env'));
+  const apiKey = process.env.OPENAI_API_KEY;
+  if (!apiKey && !dryRun) {
+    console.error('[ERROR] OPENAI_API_KEY 가 .env 또는 환경변수에 없습니다.');
+    console.error('        .env.example 을 복사해 .env 를 만들고 키를 넣으세요.');
+    console.error('        키 발급: https://platform.openai.com/api-keys');
+    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 (args.only) {
+    const n = Number(args.only);
+    slides = slides.filter((s) => s.n === n);
+    if (!slides.length) { console.error(`[ERROR] n=${n} 슬라이드 없음`); process.exit(1); }
+  }
+
+  const outDir = mode === 'slide'
+    ? join(REPO_ROOT, 'output', topic)
+    : join(REPO_ROOT, 'output', topic, 'bg');
+  mkdirSync(outDir, { recursive: true });
+
+  const build = (s) => [commonStyle, s.prompt, mode === 'slide' ? KOREAN : NO_TEXT].filter(Boolean).join('\n\n');
+  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(`          model=${model} size=${size} quality=${quality}`);
+    if (mode === 'slide') console.log(`          → 생성 후 ${BASE_W}×${BASE_H} 의 ${SCALE}배로 크롭\n`);
+    else console.log('');
+    for (const s of slides) {
+      console.log(`--- ${name(s.n)} (${s.role || '?'}) ---`);
+      console.log(build(s) + '\n'); // 자르지 않는다 — dry-run 은 가드까지 눈으로 확인하는 자리다
+    }
+    return;
+  }
+
+  console.log(`\nmode=${mode} · ${slides.length}장 생성 (${model} / ${size} / ${quality})`);
+  if (mode === 'slide') {
+    console.log('⚠️  한글이 이미지 안에 들어갑니다. 매번 달라지므로 생성 후 9장 전부 눈으로 확인하세요.');
+  }
+  console.log('');
+
+  // slide 모드에서만 크롭용 브라우저를 띄운다.
+  let browser = null, page = null;
+  if (mode === 'slide') {
+    const { default: puppeteer } = await import('puppeteer');
+    browser = await puppeteer.launch({ headless: 'new', args: ['--no-sandbox', '--disable-setuid-sandbox'] });
+    page = await browser.newPage();
+    await page.setViewport({ width: BASE_W, height: BASE_H, deviceScaleFactor: SCALE });
+  }
+
+  const summary = [];
+  try {
+    for (const s of slides) {
+      const outPath = join(outDir, name(s.n));
+      process.stdout.write(`[${s.n}/${slides.length}] ${s.role || '?'} ... `);
+      const t0 = Date.now();
+      try {
+        let buf = await generateOne({ prompt: build(s), model, size, quality, apiKey });
+        if (mode === 'slide') buf = await cropTo45(buf, page);
+        writeFileSync(outPath, buf);
+        const kb = Math.round(statSync(outPath).size / 1024);
+        const dt = ((Date.now() - t0) / 1000).toFixed(1);
+        console.log(`OK (${dt}s, ${kb}KB) -> ${name(s.n)}`);
+        summary.push([name(s.n), 'OK', `${dt}s`, `${kb}KB`]);
+      } 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 browser?.close();
+  }
+
+  console.log('\n=== SUMMARY ===');
+  summary.forEach(([f, st, dt, info]) => console.log(`  ${f.padEnd(12)} ${st.padEnd(5)} ${dt.padStart(7)}  ${info}`));
+  console.log(`\n출력: ${outDir}`);
+  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/quality-check-text.js

@@ -0,0 +1,95 @@
+#!/usr/bin/env node
+/**
+ * 카피(글) 기계 검사 — 금칙어 / 글자 수 / 구조.
+ *
+ * 원본 레포에 없는 추가분입니다. 원본 `quality-check.js` 는 손대지 않았습니다.
+ * 원본은 이미지 파이프라인용(프롬프트 JSON 스키마 + PNG 해상도)이라
+ * 텍스트 카피에는 적용되지 않습니다. 이 파일이 그 자리를 텍스트용으로 채웁니다.
+ *
+ * 사용법:
+ *   node scripts/quality-check-text.js --file output/<topic>/copy.md
+ */
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+const BANNED = JSON.parse(readFileSync(new URL('../knowledge/banned-words.json', import.meta.url), 'utf8'));
+const HEADLINE_MAX = 20;  // carousel-structure.md: 헤드라인 한 줄
+const THREAD_MAX = 500;   // thread-structure.md: 글 하나
+
+const words = () => Object.entries(BANNED)
+  .filter(([k]) => !k.startsWith('_'))
+  .flatMap(([group, list]) => list.map((w) => ({ group, w })));
+
+// `##` 로 시작하는 줄이 조각 구분자 (knowledge/patterns/*.md 의 출력 형식).
+export function parseBlocks(text) {
+  const out = [];
+  let cur = null;
+  text.split(/\r?\n/).forEach((line, i) => {
+    const m = /^##\s+(.*)$/.exec(line);
+    if (m) { cur = { title: m[1].trim(), line: i + 1, body: [] }; out.push(cur); }
+    else if (cur) cur.body.push(line);
+  });
+  return out.map((b) => ({ ...b, text: b.body.join('\n').trim() }));
+}
+
+export function detectMode(blocks) {
+  if (blocks.some((b) => /Cover/i.test(b.title))) return 'cardnews';
+  if (blocks.some((b) => /^\d+\s*\(훅\)/.test(b.title))) return 'thread';
+  return 'unknown';
+}
+
+export function check(text) {
+  const issues = [];
+  const add = (level, msg, line) => issues.push({ level, msg, line });
+  const lines = text.split(/\r?\n/);
+
+  for (const { group, w } of words()) {
+    lines.forEach((l, i) => { if (l.includes(w)) add('error', `금칙어(${group}): "${w}"`, i + 1); });
+  }
+
+  const blocks = parseBlocks(text);
+  const mode = detectMode(blocks);
+  if (!blocks.length) {
+    add('error', '## 로 시작하는 조각이 없습니다 — 출력 형식이 깨졌습니다', 1);
+    return { mode, blocks, issues };
+  }
+
+  if (mode === 'cardnews') {
+    const slides = blocks.filter((b) => /^\d{2}\s*·/.test(b.title));
+    if (slides.length !== 9) add('error', `슬라이드가 ${slides.length}장입니다 (9장이어야 함)`, 1);
+    if (!blocks.some((b) => b.title.includes('캡션'))) add('warn', '인스타 캡션 조각이 없습니다', 1);
+    for (const b of blocks) {
+      const idx = b.body.findIndex((l) => l.startsWith('헤드라인:'));
+      if (idx < 0) continue;
+      // `헤드라인:` 줄 + 이어지는 들여쓴 줄이 한 헤드라인
+      for (let i = idx; i < b.body.length; i++) {
+        if (i > idx && !/^\s{2,}\S/.test(b.body[i])) break;
+        const t = (i === idx ? b.body[i].replace(/^헤드라인:/, '') : b.body[i]).replace(/\*\*/g, '').trim();
+        if (t.length > HEADLINE_MAX) add('error', `헤드라인 ${t.length}자 (${HEADLINE_MAX}자 이내): "${t}"`, b.line + i + 1);
+      }
+    }
+  } else if (mode === 'thread') {
+    const posts = blocks.filter((b) => !/글자\s*수/.test(b.title));
+    if (posts.length < 3 || posts.length > 5) add('error', `글이 ${posts.length}개입니다 (3~5개여야 함)`, 1);
+    for (const b of posts) {
+      if (b.text.length > THREAD_MAX) add('error', `${b.title}: ${b.text.length}자 (${THREAD_MAX}자 이내)`, b.line);
+    }
+  } else {
+    add('warn', '모드를 판별하지 못했습니다 — 제목 형식을 확인하세요', 1);
+  }
+
+  return { mode, blocks, issues };
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+  const i = process.argv.indexOf('--file');
+  if (i < 0 || !process.argv[i + 1]) {
+    console.error('사용: node scripts/quality-check-text.js --file <copy.md>');
+    process.exit(2);
+  }
+  const { mode, blocks, issues } = check(readFileSync(process.argv[i + 1], 'utf8'));
+  console.log(`모드: ${mode} · 조각 ${blocks.length}개`);
+  if (!issues.length) console.log('PASS — 위반 0건');
+  else issues.forEach((x) => console.log(`${x.level === 'error' ? 'FAIL' : 'WARN'}  L${x.line}  ${x.msg}`));
+  process.exit(issues.some((x) => x.level === 'error') ? 1 : 0);
+}

package/scripts/quality-check.js

@@ -0,0 +1,206 @@
+#!/usr/bin/env node
+/**
+ * 인스타 캐러셀 품질 자동 검사.
+ *
+ * 2 모드:
+ *   1. JSON 검증: --prompt templates/slides.<topic>.json
+ *      - 9장 구조, common_style 존재, n 1~9 순차, role/prompt 필수
+ *   2. PNG 검증: --dir output/<topic>
+ *      - 9장 PNG 존재, 해상도 1080×1350 의 정수배(레티나 허용), 배율 통일, 파일 크기 분포
+ *        (인스타는 업로드 시 가로 1080 으로 줄이므로 2x=2160×2700 도 정상)
+ *
+ * 사용법:
+ *   node scripts/quality-check.js --prompt templates/slides.claude-code.json
+ *   node scripts/quality-check.js --dir output/claude-code-tips
+ */
+import { readFileSync, existsSync, readdirSync, statSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+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;
+}
+
+function checkPromptJson(path) {
+  if (!existsSync(path)) {
+    return { status: 'FAIL', errors: [`파일 없음: ${path}`] };
+  }
+  let data;
+  try {
+    data = JSON.parse(readFileSync(path, 'utf-8'));
+  } catch (e) {
+    return { status: 'FAIL', errors: [`JSON 파싱 실패: ${e.message}`] };
+  }
+
+  const errors = [];
+  const warnings = [];
+
+  if (!data.common_style || data.common_style.length < 50) {
+    errors.push('common_style 누락 또는 너무 짧음');
+  }
+  if (!Array.isArray(data.slides)) {
+    errors.push('slides 배열 누락');
+    return { status: 'FAIL', errors };
+  }
+  if (data.slides.length !== EXPECT) {
+    warnings.push(`슬라이드 ${data.slides.length}장 (권장: ${EXPECT}장)`);
+  }
+
+  for (let i = 0; i < data.slides.length; i++) {
+    const s = data.slides[i];
+    const expectedN = i + 1;
+    if (s.n !== expectedN) errors.push(`slides[${i}].n 이 ${s.n} (기대: ${expectedN})`);
+    if (!s.role) errors.push(`slides[${i}].role 누락`);
+    if (!s.prompt || s.prompt.length < 50) errors.push(`slides[${i}].prompt 누락 또는 너무 짧음`);
+  }
+
+  const coverExists = data.slides.some((s) => /cover/i.test(s.role));
+  const outroExists = data.slides.some((s) => /outro|closing/i.test(s.role));
+  if (!coverExists) warnings.push('Cover 슬라이드 없음 (권장)');
+  if (!outroExists) warnings.push('Outro 슬라이드 없음 (권장)');
+
+  return {
+    status: errors.length > 0 ? 'FAIL' : warnings.length > 0 ? 'WARN' : 'PASS',
+    errors,
+    warnings,
+    slide_count: data.slides.length,
+  };
+}
+
+// 기대 장수. main() 에서 --count 또는 gen.json 으로 덮어쓴다.
+let EXPECT = 9;
+
+const BASE_W = 1080;
+const BASE_H = 1350;
+
+// PNG 헤더(IHDR)에서 폭·높이를 직접 읽는다. 의존성 없이 8~24바이트만 보면 된다.
+function pngSize(fp) {
+  const b = readFileSync(fp);
+  const MAGIC = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+  if (b.length < 24 || !b.subarray(0, 8).equals(MAGIC)) return null; // PNG 아님/깨짐
+  return { w: b.readUInt32BE(16), h: b.readUInt32BE(20) };
+}
+
+function checkPngDir(dir) {
+  if (!existsSync(dir)) {
+    return { status: 'FAIL', errors: [`폴더 없음: ${dir}`] };
+  }
+
+  const files = readdirSync(dir)
+    .filter((f) => /^slide-\d{2}\.png$/.test(f))
+    .sort();
+
+  const errors = [];
+  const warnings = [];
+  const sizes = [];
+
+  if (files.length !== EXPECT) {
+    errors.push(`slide-*.png ${files.length}장 (기대: ${EXPECT}장)`);
+  }
+
+  const expected = Array.from({ length: EXPECT }, (_, i) => `slide-${String(i + 1).padStart(2, '0')}.png`);
+  for (const name of expected) {
+    if (!files.includes(name)) errors.push(`${name} 누락`);
+  }
+
+  const scales = new Set();
+
+  for (const f of files) {
+    const fp = join(dir, f);
+    const st = statSync(fp);
+    const dim = pngSize(fp);
+
+    sizes.push({ file: f, kb: Math.round(st.size / 1024), w: dim?.w ?? null, h: dim?.h ?? null });
+
+    if (!dim) {
+      errors.push(`${f} PNG 헤더를 읽을 수 없음 (깨진 파일)`);
+    } else {
+      // 인스타는 업로드 시 가로 1080 으로 줄인다. 1080×1350 또는 그 정수배(레티나)만 허용.
+      const scale = dim.w / BASE_W;
+      if (!Number.isInteger(scale) || scale < 1 || dim.h !== BASE_H * scale) {
+        errors.push(`${f} 해상도 ${dim.w}×${dim.h} — ${BASE_W}×${BASE_H} 의 정수배여야 함`);
+      } else {
+        scales.add(scale);
+      }
+    }
+
+    if (st.size < 20 * 1024) warnings.push(`${f} 너무 작음 (${Math.round(st.size / 1024)}KB, 깨진 이미지 가능)`);
+    if (st.size > 3 * 1024 * 1024) warnings.push(`${f} 너무 큼 (${Math.round(st.size / 1024)}KB)`);
+  }
+
+  // 9장이 서로 다른 배율이면 캐러셀에서 크기가 튄다.
+  if (scales.size > 1) errors.push(`배율이 섞여 있음: ${[...scales].sort().map((s) => `${s}x`).join(', ')}`);
+
+  return {
+    status: errors.length > 0 ? 'FAIL' : warnings.length > 0 ? 'WARN' : 'PASS',
+    errors,
+    warnings,
+    slide_count: files.length,
+    scale: scales.size === 1 ? [...scales][0] : null,
+    sizes,
+  };
+}
+
+function icon(s) {
+  return s === 'PASS' ? '✅' : s === 'WARN' ? '⚠️ ' : '❌';
+}
+
+function main() {
+  const args = parseArgs(process.argv);
+  // 빌더에서 장수를 고를 수 있게 되면서 9장 고정이 깨졌다.
+  // --count 로 주거나, 없으면 결과 폴더의 gen.json 에 기록된 값을 쓴다.
+  if (args.count) EXPECT = Number(args.count);
+  else if (args.dir) {
+    try { EXPECT = JSON.parse(readFileSync(join(args.dir, 'gen.json'), 'utf8')).count || EXPECT; } catch { /* 없으면 기본값 */ }
+  }
+  console.log('\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+  console.log('📊 캐러셀 품질 검사');
+  console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+
+  let result;
+  if (args.prompt) {
+    console.log(`[모드] 프롬프트 JSON 검증: ${args.prompt}`);
+    result = checkPromptJson(args.prompt);
+  } else if (args.dir) {
+    console.log(`[모드] PNG 폴더 검증: ${args.dir}`);
+    result = checkPngDir(args.dir);
+  } else {
+    console.error('❌ --prompt <json> 또는 --dir <folder> 중 하나 필수');
+    process.exit(1);
+  }
+
+  console.log(`\n${icon(result.status)} 상태: ${result.status}`);
+  console.log(`   슬라이드 수: ${result.slide_count ?? '?'} / ${EXPECT}`);
+
+  if (result.errors && result.errors.length > 0) {
+    console.log('\n❌ Errors:');
+    result.errors.forEach((e) => console.log(`   - ${e}`));
+  }
+  if (result.warnings && result.warnings.length > 0) {
+    console.log('\n⚠️  Warnings:');
+    result.warnings.forEach((w) => console.log(`   - ${w}`));
+  }
+  if (result.scale) console.log(`   배율: ${result.scale}x (${1080 * result.scale}×${1350 * result.scale})`);
+
+  if (result.sizes) {
+    console.log('\n📦 파일:');
+    result.sizes.forEach((s) => console.log(`   ${s.file}: ${s.w ?? '?'}×${s.h ?? '?'}, ${s.kb} KB`));
+  }
+
+  const reportDir = args.dir || (args.prompt ? args.prompt.replace(/\.json$/, '') : '.');
+  const reportPath = args.dir ? join(args.dir, 'quality-report.json') : null;
+  if (reportPath) {
+    writeFileSync(reportPath, JSON.stringify({ ...result, checked_at: new Date().toISOString() }, null, 2));
+    console.log(`\n📄 리포트: ${reportPath}`);
+  }
+
+  console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n');
+  process.exit(result.status === 'FAIL' ? 1 : 0);
+}
+
+main();