kasaframe 0.0.0-stage → 0.1.1

package/packages/cli/src/commands/make.ts

@@ -0,0 +1,542 @@
+import { spawnSync } from "node:child_process";
+import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { basename, extname, join, resolve } from "node:path";
+import { createInterface } from "node:readline/promises";
+import { fileURLToPath } from "node:url";
+import { genImage, genVideo, hasKey, NeedsApproval, seam, seamFrames, still, whereToPut } from "@kasaframe/gen";
+import { attachStudio, chat, codeBlock, detect, formatLook, jsonBlock, listTemplates, loadTemplate, look, lookSheet, type Message, type Plan, projectBrief, PURPOSES, type Purpose, readProject, writeCaptions } from "@kasaframe/plan";
+import { transform } from "esbuild";
+import { themeStyle } from "@kasaframe/themes";
+import { captionMode } from "@kasaframe/motion/captions";
+import { openPage } from "../browser.ts";
+import { type Command, num, parseFlags } from "../command.ts";
+
+const kfBin = fileURLToPath(new URL("../kf.ts", import.meta.url));
+
+// Claude Code 를 OG 로 다른 모델(딥시크 등)에 붙이면 OG /v1/messages 가 그림을 버린다 — 세션이 kf sheet 를 Read 해도 못 본다.
+// 그런 「눈 없는 세션」이면 --finish 끝에 --vision-model 을 알려 준다(그림 보는 모델은 기본으로 부르지 않는다)
+export const eyelessSession = (): boolean =>
+  /opengateway/i.test(process.env.ANTHROPIC_BASE_URL ?? "") && !/^anthropic\//.test(process.env.ANTHROPIC_MODEL ?? "anthropic/");
+const AUDIO = /\.(mp3|wav|m4a|aac|flac|ogg)$/i;
+const DEFAULT_MODEL = "deepseek/deepseek-v4-pro";
+const DEFAULT_VISION = "google/gemini-3.5-flash";
+// 화면에 찍히면 안 되는 글 — 지난 실험에서 실제로 나온 것들
+const BAD_TEXT = /\bundefined\b|\bNaN\b|\[object Object\]|\bnull\b|�/;
+
+const cmd: Command = {
+  summary: "요청 한 줄로 끝까지 — 용도 판별·계획·생성 자산·장면 작성·렌더·검사·고치기",
+  usage: `kf make "<요청>" [--out 폴더] [--assets 폴더] [--music 곡] [--model claude-code|<OG 모델>] [--purpose 용도] [--title 이름] [--yes]
+kf make --finish <폴더> [--model ...]     장면을 다 채운 뒤 렌더·검사·표지(Claude Code 모드의 둘째 단계)
+kf make --rewrite <폴더> --scenes a,b [--model <OG 모델>]   고른 장면만 다시 쓰고 렌더·검사(작업실 장면 카드)
+
+  --model         claude-code: 장면 지시서(MAKE.md)까지 만들고 멈춘다 — Claude Code 가 장면을 채우고 --finish
+                  <OG 모델>: OG chat/completions 로 장면을 쓰고 렌더·검사·고치기까지(기본 ${DEFAULT_MODEL})
+                  Claude Code 안(CLAUDECODE=1)에서 부르면 기본이 claude-code
+  --vision-model  그림 보는 검사 모델(기본 none — 세션이 kf look 의 장면 모음·확인표를 직접 본다). 그림을 못 보는 세션만 ${DEFAULT_VISION} 같은 모델을 준다
+  --purpose       용도를 못 박는다: ${PURPOSES.join(" · ")}
+  --theme         테마 id · auto(기본 — 요청이 「리소 느낌」처럼 짚은 테마, 아니면 내용에 맞는 approved 후보 셋 중 첫째. 첫 장면을 셋 다 찍어 out/theme-<id>.png) · none(프리셋만)
+  --yes           영상 생성처럼 돈이 큰 호출을 승인한다(없으면 견적만 보이고 이음매는 대체 화면으로 간다)
+  --max-usd       영상 하나 상한(기본 1)
+  --video-provider  영상 공급자를 못 박는다(예: h3-pod — KF_H3_URL·KF_H3_STEPS 필요). 기본은 KF_VIDEO_PROVIDER, 없으면 생성 담당 기본
+  --fix           검사가 떨어졌을 때 고치기 횟수(기본 2)
+  --captions on|off|fit  화면 자막(fit 은 장면을 자막 띠 위로 줄여 올린다) — 새로 만들 땐 kf.json 에 적고, --finish 에선 그 판만 덮는다(다시 만들지 않고 켜고 끄기). srt·vtt 는 둘 다 낸다
+  --suffix [글]   --finish 결과 이름 뒤에 붙인다(값 없이면 -자막 · -자막없음) — 원본 video.mp4 를 덮지 않고 둘 다 남긴다
+  --no-gen        생성 모델을 부르지 않는다. claude-code 모드는 묻지 않고 그림을 만들지 않는다 — 지시서의 「만들 그림」을 보고 세션이 프롬프트를 써서 kf gen img 로 만든다
+
+용도를 못 정하면 터미널에서 묻고, 터미널이 아니면 보기를 찍고 종료 코드 3.`,
+  async run(argv) {
+    const { args, opts } = parseFlags(argv);
+    const str = (k: string) => (typeof opts[k] === "string" ? (opts[k] as string) : undefined);
+    // --finish 는 Claude Code 모드의 둘째 단계라 모델을 안 주면 claude-code — 세션이 직접 그림을 보니 그림 검사 모델도 부르지 않는다
+    const model = str("model") ?? (process.env.CLAUDECODE || opts.finish ? "claude-code" : DEFAULT_MODEL);
+    const vision = str("vision-model") ?? "none";
+    // OG 모드는 장면 쓰기·그림 보기까지 OG 를 부른다 — 뼈대만 만들고 죽지 않게 처음에 막는다
+    if (model !== "claude-code" && !hasKey("opengateway")) {
+      console.error(`kf make: OG 키가 없다 — ${whereToPut("opengateway")}. 키 없이는 Claude Code 안에서(또는 --model claude-code) — 장면은 세션이 쓰고 그림 생성은 건너뛴다`);
+      return 2;
+    }
+    const fixes = num(opts.fix, 2);
+    const captions = str("captions");
+    if (captions !== undefined && captions !== "on" && captions !== "off" && captions !== "fit") {
+      console.error(`kf make: --captions 는 on·off·fit — ${captions}`);
+      return 2;
+    }
+    const suffix = str("suffix") ?? (opts.suffix ? (captions === "off" ? "-자막없음" : "-자막") : "");
+
+    if (opts.rewrite) {
+      const dir = resolve(typeof opts.rewrite === "string" ? opts.rewrite : (args[0] ?? "."));
+      const ids = (str("scenes") ?? "").split(",").filter(Boolean);
+      if (!ids.length || model === "claude-code") {
+        console.error("kf make --rewrite: --scenes 와 OG 모델(--model)이 필요하다");
+        return 2;
+      }
+      writeFileSync(join(dir, "MAKE.md"), projectBrief(dir));
+      await writeScenes(dir, model, ids);
+      return finish(dir, { model, vision, fixes });
+    }
+    if (opts.finish) {
+      const dir = resolve(typeof opts.finish === "string" ? opts.finish : (args[0] ?? "."));
+      const gen = { approve: !!opts.yes, maxUsd: num(opts["max-usd"], 1), videoProvider: str("video-provider") ?? process.env.KF_VIDEO_PROVIDER };
+      const plan = existsSync(join(dir, "plan.json")) ? JSON.parse(readFileSync(join(dir, "plan.json"), "utf8")) : {};
+      const studio = await attachStudio({ dir, request: plan.request ?? dir, model, purpose: plan.purpose });
+      const unmirror = studio?.mirror();
+      if (studio) console.log(`작업실: ${studio.url}`);
+      await studio?.send({ phase: "render" });
+      const code = await finish(dir, { model, vision, fixes, gen: opts["no-gen"] ? undefined : gen, captions, suffix });
+      await unmirror?.();
+      await studio?.send({ done: true, ok: code === 0 });
+      return code;
+    }
+
+    const request = args.join(" ").trim();
+    if (!request) {
+      console.error('kf make: 요청 글이 필요하다 — kf make "카사텀 홍보 영상 1분"');
+      return 2;
+    }
+    const assetFiles = str("assets") ? listFiles(resolve(str("assets")!)) : [];
+    const given = str("music") ? resolve(str("music")!) : assetFiles.find((f) => AUDIO.test(f));
+
+    let purpose = str("purpose") as Purpose | undefined;
+    const det = detect({ request, assets: assetFiles, music: given }, listTemplates());
+    if (!purpose) {
+      if (det.ambiguous) {
+        purpose = await ask(det.ranked.slice(0, 4).map((r) => r.purpose));
+        if (!purpose) {
+          console.error(`kf make: 용도를 못 정했다(확신 ${det.confidence}). --purpose 로 골라 다시: ${det.ranked.slice(0, 4).map((r) => `${r.purpose}(${r.p})`).join(" · ")}`);
+          return 3;
+        }
+      } else purpose = det.purpose;
+    }
+    const chosen = det.ranked.find((r) => r.purpose === purpose);
+    // 곡을 안 줬으면 곡이 끌고 가는 용도(홍보·공개)일 때만 곡 모음에서 고른다 — 쇼츠·설명에 아무 곡이나 깔리지 않게
+    const music = given ?? (loadTemplate(purpose).music === "required" ? findLibraryMusic(request) : undefined);
+    console.error(`용도 ${purpose} (확신 ${chosen?.p ?? 1}${chosen?.reasons.length ? ` — ${chosen.reasons.join(", ")}` : ""})`);
+
+    const dir = resolve(str("out") ?? `${purpose}-${stamp()}`);
+    const newArgs = [kfBin, "new", dir, "--template", purpose, "--request", request];
+    if (music) newArgs.push("--music", music);
+    if (str("title")) newArgs.push("--title", str("title")!);
+    // 말로만 시작해도 테마까지 알아서 — 안 주면 auto(요청이 짚은 테마 → 내용에 맞는 approved 후보). 테마 없이 프리셋만 쓰려면 --theme none
+    const theme = str("theme") ?? "auto";
+    if (theme !== "none") newArgs.push("--theme", theme);
+    if (opts.force) newArgs.push("--force");
+    const made = spawnSync(process.execPath, newArgs, { stdio: ["ignore", "inherit", "inherit"] });
+    if (made.status !== 0) return made.status ?? 1;
+
+    const studio = await attachStudio({ dir, request, model, purpose });
+    const unmirror = studio?.mirror();
+    if (studio) console.log(`작업실: ${studio.url}`);
+    const plan: Plan = JSON.parse(readFileSync(join(dir, "plan.json"), "utf8"));
+    // 새 프로젝트는 이 영상의 기본으로 적는다 — 계획 다듬기가 내레이션을 쓸지도 이걸 본다
+    if (captions) {
+      const kfPath = join(dir, "kf.json");
+      writeJson(kfPath, { ...JSON.parse(readFileSync(kfPath, "utf8")), captions });
+      plan.captions = captionMode(captions);
+    }
+    if (!str("purpose")) {
+      plan.confidence = chosen?.p ?? det.confidence;
+      plan.alternatives = det.ranked.filter((r) => r.purpose !== purpose).slice(0, 2).map((r) => ({ purpose: r.purpose, p: r.p }));
+      plan.reasons = [...(chosen?.reasons ?? []), ...plan.reasons.filter((r) => r !== "사람이 정함")];
+    }
+    if (assetFiles.length) {
+      mkdirSync(join(dir, "assets", "in"), { recursive: true });
+      for (const f of assetFiles) if (!AUDIO.test(f)) copyFileSync(f, join(dir, "assets", "in", basename(f)));
+    }
+    writeJson(join(dir, "plan.json"), plan);
+    if (plan.theme) {
+      const pick = plan.themeCandidates?.find((c) => c.id === plan.theme);
+      console.error(`테마 ${plan.theme}${pick ? ` — ${pick.why}` : ""}${plan.themeCandidates && plan.themeCandidates.length > 1 ? ` (다른 후보: ${plan.themeCandidates.filter((c) => c.id !== plan.theme).map((c) => c.id).join(" · ")})` : ""}`);
+    }
+    if (plan.themeCandidates && plan.themeCandidates.length > 1) themeStills(dir, plan.themeCandidates.map((c) => c.id));
+
+    if (model !== "claude-code") await refinePlan(dir, model, request);
+
+    const gen = { approve: !!opts.yes, maxUsd: num(opts["max-usd"], 1), videoProvider: str("video-provider") ?? process.env.KF_VIDEO_PROVIDER };
+    // claude-code 모드는 돈이 드는 그림을 묻지 않고 만들지 않는다 — 막연한 자동 프롬프트로 엉뚱한 그림이 나왔다. 지시서에 목록으로 낸다
+    if (!opts["no-gen"] && model !== "claude-code") await genImages(dir);
+
+    writeFileSync(join(dir, "MAKE.md"), projectBrief(dir));
+    if (model === "claude-code") {
+      const flags = [gen.approve ? "--yes" : "", gen.videoProvider ? `--video-provider ${gen.videoProvider}` : ""].filter(Boolean).join(" ");
+      console.log(`\n${dir}/MAKE.md 를 읽고 scenes/*.ts 를 채운다. 다 채우면(이음매 영상은 그때 앞뒤 장면 프레임으로 만든다):\n  kf make --finish ${dir}${flags ? ` ${flags}` : ""}`);
+      // 장면은 세션이 쓴다 — 작업실 미리보기가 저장할 때마다 따라온다
+      console.error("장면 쓰는 중(세션) — 저장할 때마다 작업실 미리보기에 바로 보인다");
+      await unmirror?.();
+      await studio?.send({ phase: "scenes" });
+      return 0;
+    }
+    // 이음매는 틀의 3D 전환이 맡는다 — 모델이 다시 쓰지 않는다
+    await writeScenes(dir, model, readProject(dir).scenes.filter((s) => s.role !== "seam").map((s) => s.id));
+    const code = await finish(dir, { model, vision, fixes, gen: opts["no-gen"] ? undefined : gen });
+    await unmirror?.();
+    await studio?.send({ done: true, ok: code === 0 });
+    return code;
+  },
+};
+export default cmd;
+
+// --- 계획 다듬기: 틀이 정한 뼈대(시각·역할)는 그대로, 이름·끝 한 줄·장면 할 일·생성 프롬프트만 요청에 맞춘다
+
+async function refinePlan(dir: string, model: string, request: string): Promise<void> {
+  const plan: Plan = JSON.parse(readFileSync(join(dir, "plan.json"), "utf8"));
+  const kf = JSON.parse(readFileSync(join(dir, "kf.json"), "utf8"));
+  const ask: Message[] = [
+    {
+      role: "system",
+      content:
+        "너는 짧은 영상의 연출 계획을 다듬는다. 장면 id·순서·시각은 바꾸지 않는다. 화면에 쓸 글 정책을 지킨다. JSON 하나로만 답한다.",
+    },
+    {
+      role: "user",
+      content: `요청: ${request}
+용도: ${plan.purpose} · ${plan.duration}초 · ${plan.aspect} · 스타일 ${plan.style} · 화면 글 정책 ${kf.text?.policy}
+장면: ${JSON.stringify(plan.scenes.map((s) => ({ id: s.id, role: s.role, dur: s.dur, idea: s.idea })))}
+생성 자산: ${JSON.stringify(plan.gen.map((g) => ({ id: g.id, kind: g.kind, scene: g.scene, prompt: g.prompt })))}
+
+다음 꼴로: {"title": "제품·주제 이름(짧게)", "line": "끝 카드 한 줄(없으면 빈 글)", "scenes": [{"id": "...", "idea": "이 요청에 맞춘 구체적인 화면·움직임 한두 문장"}], "gen": [{"id": "...", "prompt": "영어 생성 프롬프트, 글자·로고 없이"}]${captionMode(kf.captions) !== "none" ? ', "captions": [{"scene": "장면 id", "text": "그 장면에서 들릴 한국어 내레이션 — 짧은 마디를 쉼표로 이어 장면 길이에 맞게(1초에 4~5글자)"}]' : ""}}`,
+    },
+  ];
+  try {
+    // 생각하는 모델은 생각에 토큰을 먼저 쓴다 — 상한이 낮으면 답 JSON 이 잘린다
+    const r = await chat(model, ask, { json: true, temperature: 0.5, maxTokens: 16000 });
+    const j = jsonBlock<{ title?: string; line?: string; scenes?: { id: string; idea: string }[]; gen?: { id: string; prompt: string }[]; captions?: { scene: string; text: string }[] }>(r.text);
+    if (!j) throw new Error(`JSON 을 못 읽었다(${r.text.length}자: ${r.text.slice(0, 160).replace(/\s+/g, " ")})`);
+    if (j.title) plan.title = kf.title = j.title;
+    for (const s of j.scenes ?? []) {
+      const p = plan.scenes.find((x) => x.id === s.id);
+      const k = kf.scenes.find((x: { id: string }) => x.id === s.id);
+      if (p && s.idea) p.idea = k.idea = s.idea;
+    }
+    for (const g of j.gen ?? []) {
+      const p = plan.gen.find((x) => x.id === g.id);
+      if (p && g.prompt) p.prompt = g.prompt;
+    }
+    (plan as Plan & { line?: string }).line = j.line ?? "";
+    if (captionMode(kf.captions) !== "none" && j.captions?.length) writeJson(join(dir, "captions.json"), j.captions);
+    writeJson(join(dir, "plan.json"), plan);
+    writeJson(join(dir, "kf.json"), kf);
+    console.error(`계획 다듬음(${model}, ${(r.ms / 1000).toFixed(1)}초): ${plan.title}`);
+  } catch (e) {
+    console.error(`계획 다듬기 건너뜀 — ${e instanceof Error ? e.message : e}`);
+  }
+}
+
+// --- 장면 쓰기: 장면마다 파일 하나를 받아 놓고, 실제로 열어 오류·이상한 글이 없을 때까지 돌려준다
+
+async function writeScenes(dir: string, model: string, ids: string[], feedback: Record<string, string> = {}): Promise<void> {
+  const brief = readFileSync(join(dir, "MAKE.md"), "utf8");
+  const kf = readProject(dir);
+  for (const id of ids) {
+    const s = kf.scenes.find((x) => x.id === id);
+    if (!s) continue;
+    const file = join(dir, s.file);
+    let note = feedback[id] ?? "";
+    console.error(`장면 ${s.id} 쓰는 중(${model})`);
+    for (let attempt = 0; attempt < 3; attempt++) {
+      const current = existsSync(file) ? readFileSync(file, "utf8") : "";
+      const messages: Message[] = [
+        { role: "system", content: `너는 kasaframe 장면 파일을 쓴다. 아래 지시서를 지킨다. 답은 TypeScript 코드 블록 하나뿐.\n\n${brief}` },
+        {
+          role: "user",
+          content: `장면 ${s.id}(${s.file}, ${s.dur.toFixed(2)}초, 역할 ${s.role})의 파일 전체를 써라.\n할 일: ${s.idea}\n\n지금 파일:\n\`\`\`ts\n${current}\`\`\`${note ? `\n\n고칠 것:\n${note}` : ""}`,
+        },
+      ];
+      const r = await chat(model, messages, { temperature: 0.6, maxTokens: 32000 });
+      const code = r.finish === "length" ? null : codeBlock(r.text);
+      if (r.finish === "length") {
+        note = "답이 길이 상한에서 잘렸다. 군더더기 없이 더 짧게, ```ts 블록 하나로 파일 전체를 답하라.";
+        console.error(`  ${s.id} ${attempt + 1}번째 — 답이 잘림`);
+        continue;
+      }
+      if (!code) {
+        note = "코드 블록을 못 찾았다. ```ts 블록 하나로 파일 전체를 답하라.";
+        continue;
+      }
+      writeFileSync(file, code);
+      const problems = await probeScene(dir, s.id);
+      console.error(`  ${s.id} ${attempt + 1}번째 ${(r.ms / 1000).toFixed(1)}초 — ${problems.length ? problems.join(" / ") : "통과"}`);
+      if (!problems.length) break;
+      note = problems.join("\n");
+    }
+  }
+}
+
+// 렌더 전에 장면 하나를 세 시각에서 열어 본다 — 통짜 렌더 1분을 쓰기 전에 잡을 것을 잡는다
+async function probeScene(dir: string, id: string): Promise<string[]> {
+  const kf = readProject(dir);
+  const s = kf.scenes.find((x) => x.id === id)!;
+  const problems: string[] = [];
+  // 문법이 깨지면 페이지는 「__kf 를 안 걸었다」밖에 말해 주지 않는다 — 줄·칸이 붙은 오류를 먼저 돌려준다
+  try {
+    await transform(readFileSync(join(dir, s.file), "utf8"), { loader: "ts", sourcefile: s.file });
+  } catch (e) {
+    const errs = (e as { errors?: { text: string; location?: { line: number; column: number; lineText: string } }[] }).errors ?? [];
+    return errs.length ? errs.slice(0, 3).map((x) => `문법 오류 ${s.file}:${x.location?.line}:${x.location?.column} ${x.text} — ${x.location?.lineText.trim().slice(0, 120)}`) : [`문법 오류: ${e instanceof Error ? e.message : e}`];
+  }
+  let p: Awaited<ReturnType<typeof openPage>>;
+  try {
+    p = await openPage(dir);
+  } catch (e) {
+    return [`페이지가 안 열린다: ${(e instanceof Error ? e.message : String(e)).slice(0, 600)}`];
+  }
+  const errors: string[] = [];
+  p.page.on("pageerror", (e) => errors.push(e.message));
+  try {
+    for (const t of [s.from + 0.05, s.from + s.dur / 2, s.from + s.dur - 0.05]) {
+      await p.seek(t);
+      const text: string = await p.page.evaluate(() => (document.getElementById("stage") ?? document.body).innerText);
+      const bad = text.match(BAD_TEXT);
+      if (bad) problems.push(`${(t - s.from).toFixed(2)}초 화면에 "${bad[0]}" 글자가 찍힌다`);
+      const box = await p.page.evaluate(() => {
+        const out: string[] = [];
+        const W = innerWidth;
+        const H = innerHeight;
+        for (const el of Array.from(document.querySelectorAll("#stage *"))) {
+          if (!(el as HTMLElement).innerText?.trim() || el.children.length) continue;
+          const r = el.getBoundingClientRect();
+          const cs = getComputedStyle(el);
+          if (cs.opacity === "0" || cs.visibility === "hidden" || r.width === 0) continue;
+          if (r.right < 0 || r.bottom < 0 || r.left > W || r.top > H) continue;
+          if (r.left < -2 || r.top < -2 || r.right > W + 2 || r.bottom > H + 2) out.push((el as HTMLElement).innerText.trim().slice(0, 20));
+        }
+        return out;
+      });
+      if (box.length) problems.push(`${(t - s.from).toFixed(2)}초에 글이 화면 밖으로 나간다: ${box.slice(0, 3).join(", ")}`);
+    }
+  } catch (e) {
+    problems.push(`seek 중 오류: ${e instanceof Error ? e.message : e}`);
+  } finally {
+    await p.close();
+  }
+  for (const e of new Set(errors)) problems.push(`페이지 오류: ${e}`);
+  return [...new Set(problems)];
+}
+
+// 테마 후보마다 첫 장면을 그 테마로 한 장 — 사람이 셋을 나란히 보고 고른다. style.json 만 잠깐 바꿔 찍고 되돌린다
+function themeStills(dir: string, ids: string[]): void {
+  const stylePath = join(dir, "style.json");
+  const keep = readFileSync(stylePath, "utf8");
+  const motion = JSON.parse(keep).motion;
+  const kf = readProject(dir);
+  const first = kf.scenes[0];
+  const t = +(first.from + Math.min(first.dur * 0.6, 1.2)).toFixed(3);
+  try {
+    for (const id of ids) {
+      writeJson(stylePath, { ...themeStyle(id), motion });
+      const r = spawnSync(process.execPath, [kfBin, "still", dir, "--t", String(t), "--out", join(dir, "out", `theme-${id}.png`)], { stdio: "ignore" });
+      console.error(`테마 후보 ${id}: ${r.status === 0 ? `out/theme-${id}.png` : "못 찍음"}`);
+    }
+  } finally {
+    writeFileSync(stylePath, keep);
+  }
+}
+
+// --- 생성 자산: 그림은 장면을 쓰기 전에(장면이 가져다 쓴다), 영상은 장면을 다 쓴 뒤에(이음매는 앞뒤 장면의 진짜 프레임에서 뽑는다)
+
+interface GenOpts {
+  approve: boolean;
+  maxUsd: number;
+  videoProvider?: string;
+}
+
+const genLog = (l: string) => console.error(`  ${l}`);
+
+async function genImages(dir: string): Promise<void> {
+  const plan: Plan = JSON.parse(readFileSync(join(dir, "plan.json"), "utf8"));
+  const imgs = plan.gen.filter((g) => g.kind === "img");
+  if (!imgs.length) return;
+  console.error(`생성 자산 그림 ${imgs.length}개…`);
+  for (const g of imgs) {
+    try {
+      const size = g.size ?? (plan.aspect === "9:16" ? "1080x1920" : plan.aspect === "1:1" ? "1080x1080" : "1920x1080");
+      const a = await genImage(g.id, { prompt: g.prompt, size, transparent: g.transparent, quality: g.quality, refs: g.refs?.map((r) => join(dir, r)) }, { outDir: join(dir, "assets", "gen"), log: genLog }, g.provider);
+      console.error(`  gen:img:${g.id} ${a.cached ? "cached" : "made"} ${a.path} $${(a.cached ? 0 : a.meta.costUsd).toFixed(3)}`);
+    } catch (e) {
+      console.error(`  gen:img:${g.id} ${e instanceof NeedsApproval ? "needs-approval" : "error"} ${e instanceof Error ? e.message : e}`);
+    }
+  }
+}
+
+async function genVideos(dir: string, o: GenOpts): Promise<void> {
+  const plan: Plan = JSON.parse(readFileSync(join(dir, "plan.json"), "utf8"));
+  const vids = plan.gen.filter((g) => g.kind === "vid");
+  if (!vids.length) return;
+  console.error(`생성 자산 영상 ${vids.length}개…`);
+  const ctx = { outDir: join(dir, "assets", "gen"), approve: o.approve, maxUsd: o.maxUsd, log: genLog };
+  for (const g of vids) {
+    const provider = o.videoProvider ?? g.provider;
+    try {
+      const a = g.seam
+        ? await seam({ project: dir, scene: g.id, prompt: g.prompt, provider }, ctx)
+        : await genVideo(g.id, { prompt: g.prompt, duration: g.dur ?? 5, aspect: plan.aspect, firstFrame: g.first && join(dir, g.first), lastFrame: g.last && join(dir, g.last) }, ctx, provider);
+      console.error(`  gen:vid:${g.id} ${a.cached ? "cached" : "made"} ${a.path} $${(a.cached ? 0 : a.meta.costUsd).toFixed(3)}`);
+    } catch (e) {
+      const tail = e instanceof NeedsApproval ? `needs-approval 견적 $${e.estimateUsd.toFixed(3)}(${e.provider}) — --yes 로 승인하면 만든다, 지금은 대체 화면` : `error ${e instanceof Error ? e.message : e}`;
+      console.error(`  gen:vid:${g.id} ${tail}`);
+    }
+  }
+}
+
+// 이음매 장면의 모션그래픽 전환(transition3d)은 앞 장면 마지막 화면·뒤 장면 첫 화면 두 장을 받아 그 사이를 잇는다.
+// 장면을 다 쓴 뒤에 찍어야 진짜 화면이 된다 — 그림이 없으면 전환이 style 색으로 대체 화면을 그린다
+async function seamStills(dir: string): Promise<void> {
+  const kf = JSON.parse(readFileSync(join(dir, "kf.json"), "utf8"));
+  const seams = (kf.scenes as { id: string; role: string }[]).filter((s) => s.role === "seam");
+  if (!seams.length) return;
+  mkdirSync(join(dir, "assets", "seam"), { recursive: true });
+  for (const s of seams) {
+    const { firstFrame, lastFrame } = seamFrames(kf, s.id);
+    try {
+      if (firstFrame !== undefined) await still(dir, firstFrame, join(dir, "assets", "seam", `${s.id}-from.png`));
+      if (lastFrame !== undefined) await still(dir, lastFrame, join(dir, "assets", "seam", `${s.id}-to.png`));
+      console.error(`이음매 ${s.id}: 앞뒤 화면 두 장 찍음`);
+    } catch (e) {
+      console.error(`이음매 ${s.id}: 앞뒤 화면을 못 찍었다 — 대체 화면으로 간다(${e instanceof Error ? e.message : e})`);
+    }
+  }
+}
+
+// --- 마무리: 렌더 → 검사 → (OG 모드면) 고치기 → 표지
+
+// captions 를 주면 그 판만 화면 자막을 켜고 끈다(kf.json 은 그대로) — 굽기·검사·자막 트랙이 같은 값을 본다
+async function finish(dir: string, o: { model: string; vision: string; fixes: number; gen?: GenOpts; captions?: "on" | "off" | "fit"; suffix?: string }): Promise<number> {
+  if (!existsSync(join(dir, "kf.json"))) {
+    console.error(`kf make: ${dir} 에 kf.json 이 없다`);
+    return 2;
+  }
+  if (o.gen) await genVideos(dir, o.gen);
+  await seamStills(dir);
+  const out = join(dir, "out", `video${o.suffix ?? ""}.mp4`);
+  const capFlag = o.captions ? ["--captions", o.captions] : [];
+  let verdict = { code: 0, report: "" };
+  for (let round = 0; ; round++) {
+    if (round > 0) await seamStills(dir);
+    const r = spawnSync(process.execPath, [kfBin, "render", dir, "--out", out, "--tabs", "2", ...capFlag], { stdio: ["ignore", "inherit", "inherit"] });
+    if (r.status !== 0) {
+      console.error("kf make: 렌더가 실패했다");
+      return r.status ?? 1;
+    }
+    verdict = check(dir, capFlag);
+    const review = o.vision !== "none" ? await visionReview(dir, o.vision) : {};
+    const toFix: Record<string, string> = { ...review };
+    for (const [id, note] of Object.entries(findingsByScene(dir))) toFix[id] = [toFix[id], note].filter(Boolean).join("\n");
+    if ((verdict.code === 0 && !Object.keys(review).length) || o.model === "claude-code" || round >= o.fixes) break;
+    if (!Object.keys(toFix).length) break;
+    console.error(`고치기 ${round + 1}/${o.fixes}: ${Object.keys(toFix).join(" ")}`);
+    writeFileSync(join(dir, "MAKE.md"), projectBrief(dir));
+    await writeScenes(dir, o.model, Object.keys(toFix), toFix);
+  }
+  const subs = writeCaptions(dir, o.captions && captionMode(o.captions));
+  const cover = coverTime(dir);
+  spawnSync(process.execPath, [kfBin, "still", dir, "--t", String(cover), "--out", join(dir, "out", "cover.png")], { stdio: "ignore" });
+  console.log(`\n${[out, join(dir, "out", "cover.png"), ...subs].join("\n")}`);
+  if (o.vision === "none") lookHint(dir);
+  if (verdict.report) console.log(`\n검사:\n${verdict.report}`);
+  return verdict.code;
+}
+
+// 폴더를 주면 kf check 가 페이지를 열어 프레임마다 훑는다 — mp4 를 OCR 하는 것보다 정확하다
+function check(dir: string, extra: string[] = []): { code: number; report: string } {
+  const r = spawnSync(process.execPath, [kfBin, "check", dir, ...extra], { encoding: "utf8" });
+  return { code: r.status ?? 1, report: `${r.stdout ?? ""}${r.stderr ?? ""}`.trim() };
+}
+
+// out/check.json 의 오류를 시각으로 장면에 묶는다 — 장면마다 자기 몫의 지적만 받아 다시 쓴다
+function findingsByScene(dir: string): Record<string, string> {
+  const file = join(dir, "out", "check.json");
+  if (!existsSync(file)) return {};
+  const kf = readProject(dir);
+  const report = JSON.parse(readFileSync(file, "utf8")) as { findings?: { rule: string; severity: string; from: number; to?: number; message: string }[] };
+  const out: Record<string, string[]> = {};
+  for (const f of report.findings ?? []) {
+    if (f.severity !== "error") continue;
+    const s = kf.scenes.find((x) => f.from >= x.from && f.from < x.from + x.dur) ?? kf.scenes.at(-1)!;
+    (out[s.id] ??= []).push(`[${f.rule}] 장면 안 ${(f.from - s.from).toFixed(2)}초${f.to !== undefined ? `–${(f.to - s.from).toFixed(2)}초` : ""}: ${f.message}`);
+  }
+  return Object.fromEntries(Object.entries(out).map(([k, v]) => [k, `검사(kf check):\n${v.join("\n")}`]));
+}
+
+// 그림 보는 모델을 안 부를 때 — 세션이 직접 볼 장면 모음·확인표를 만들어 경로를 찍는다
+function lookHint(dir: string): void {
+  try {
+    const s = lookSheet(dir);
+    console.log(`\n직접 볼 것: ${s.sheet}\n확인표:     ${s.checklist}`);
+  } catch (e) {
+    console.error(`장면 모음을 못 만들었다 — ${e instanceof Error ? e.message : e}`);
+  }
+  if (eyelessSession()) console.log(`그림이 안 보이는 세션이면: kf look ${dir} --vision-model ${DEFAULT_VISION}`);
+}
+
+// 장면 모음을 그림 보는 모델에 보여 주고(kf look --vision-model), 고칠 장면만 받아 온다
+async function visionReview(dir: string, model: string): Promise<Record<string, string>> {
+  try {
+    const r = await look(dir, { model });
+    console.error(formatLook(r));
+    return Object.fromEntries(r.scenes.filter((s) => !s.ok).map((s) => [s.id, `그림 검사(${model}): ${s.problems.join(" / ")}`]));
+  } catch (e) {
+    console.error(`그림 검사 건너뜀 — ${e instanceof Error ? e.message : e}`);
+    return {};
+  }
+}
+
+function coverTime(dir: string): number {
+  const kf = readProject(dir);
+  const pick = kf.scenes.find((s) => s.role === "drop") ?? kf.scenes.find((s) => s.role === "hook" || s.role === "reveal") ?? kf.scenes[0];
+  return +(pick.from + Math.min(0.8, pick.dur / 2)).toFixed(3);
+}
+
+// --- 그 밖
+
+async function ask(choices: Purpose[]): Promise<Purpose | undefined> {
+  if (!process.stdin.isTTY) return undefined;
+  const labels = listTemplates();
+  const rl = createInterface({ input: process.stdin, output: process.stderr });
+  const lines = choices.map((c, i) => `  ${i + 1}) ${c} — ${labels.find((t) => t.id === c)?.label}`).join("\n");
+  const a = await rl.question(`어떤 용도의 영상인가?\n${lines}\n번호: `);
+  rl.close();
+  return choices[Number(a) - 1];
+}
+
+// 곡을 안 줬을 때 KF_MUSIC_DIR(저작권 걱정 없는 곡 모음)에서 요청 낱말과 이름이 맞는 곡을 고른다.
+// 곡 파일 이름은 대개 영어라 한국어 장르 낱말을 영어로도 찾는다
+const GENRE: Record<string, string[]> = {
+  카와이: ["kawaii", "cute"],
+  귀여운: ["kawaii", "cute"],
+  퓨처베이스: ["future", "bass"],
+  칠: ["chill", "lofi"],
+  로파이: ["lofi", "lo-fi"],
+  몽환: ["dream", "ambient"],
+  신나는: ["upbeat", "energetic", "edm"],
+  잔잔한: ["calm", "ambient", "piano"],
+  애니: ["anime"],
+  시네마틱: ["cinematic", "epic"],
+};
+
+// 기본 곡 모음은 레포의 music/(README 에 곡마다 원본·라이선스). KF_MUSIC_DIR 이 있으면 그쪽
+const musicDir = (): string => process.env.KF_MUSIC_DIR || fileURLToPath(new URL("../../../../music/", import.meta.url));
+
+function findLibraryMusic(request: string): string | undefined {
+  const lib = musicDir();
+  if (!existsSync(lib)) return undefined;
+  const songs = listFiles(lib).filter((f) => AUDIO.test(f));
+  const words = request.toLowerCase().split(/[\s,]+/).filter((w) => w.length > 1);
+  const wanted = [...words, ...Object.entries(GENRE).filter(([k]) => request.includes(k)).flatMap(([, v]) => v)];
+  const score = (f: string) => wanted.filter((w) => basename(f, extname(f)).toLowerCase().includes(w)).length;
+  return songs.sort((a, b) => score(b) - score(a))[0];
+}
+
+function listFiles(dir: string): string[] {
+  if (!existsSync(dir)) return [];
+  if (statSync(dir).isFile()) return [dir];
+  return readdirSync(dir, { withFileTypes: true }).flatMap((e) => (e.isDirectory() ? readdirSync(join(dir, e.name)).map((f) => join(dir, e.name, f)) : [join(dir, e.name)]));
+}
+
+function stamp(): string {
+  const d = new Date();
+  const p = (n: number) => String(n).padStart(2, "0");
+  return `${d.getFullYear()}${p(d.getMonth() + 1)}${p(d.getDate())}-${p(d.getHours())}${p(d.getMinutes())}`;
+}
+
+function writeJson(path: string, v: unknown): void {
+  writeFileSync(path, `${JSON.stringify(v, null, 2)}\n`);
+}