kasaframe 0.0.0-stage → 0.1.3

package/packages/gen/src/ask.ts

@@ -0,0 +1,132 @@
+import { createInterface } from "node:readline/promises";
+
+// 돈이 드는 호출과 없는 능력은 kf make 가 생성 전에 한 번에 모아 묻는다 — 그림·영상·3D·음악·목소리가 같은 꼴로 들어온다
+// theme 은 돈도 능력도 아닌 고르기라 --allow 목록엔 없다 — --yes·--no-gen·--allow 는 그 질문의 「알아서」로 간다
+export type Capability = "image" | "video" | "blender" | "three" | "music" | "voice" | "beats" | "lyrics" | "theme";
+export const CAPABILITIES: Capability[] = ["image", "video", "blender", "three", "music", "voice", "beats", "lyrics"];
+// --no-gen 이 「빼기」로 답해 줄 수 있는 생성 능력 — 3D·박자·가사 도구는 생성 모델이 아니라 --no-gen 으로 넘기지 않는다
+const GENERATIVE = new Set<Capability>(["image", "video", "music", "voice"]);
+// 「키·도구를 넣고 다시」 — 고르면 kf make 가 켜는 법을 찍고 종료 3
+export const WAIT = "wait";
+
+export interface Choice {
+  value: string; // --<flag> 에 그대로 넣는 값
+  label: string;
+  costUsd?: number;
+  note?: string; // 라이선스·지역 경고는 여기 — 묻는 글과 결과 메타에 같이 남는다
+}
+
+export interface Question {
+  id: string;
+  cap: Capability; // --allow 로 묻지 않고 허락하는 단위
+  ask: string;
+  header: string; // 12자 이내 — Claude Code AskUserQuestion 칩
+  choices: Choice[]; // 첫째가 권장
+  default: string; // --yes · --allow <cap> · 터미널 엔터
+  skip: string; // --no-gen · --allow 에 cap 이 없을 때 — 돈 안 드는 길
+  flag: string;
+  // 필요한 능력이 없다 — 조용히 대체하지 않는다. 보기는 ① 넣는 법(wait, 권장) ② 지금 쓸 수 있는 다른 엔진 ③ 빼기.
+  // --yes·--allow 로 넘어가지 않고 사람이 준 답(플래그·--answer·시리즈)만, 생성 능력이면 --no-gen 의 빼기만 받는다
+  missing?: boolean;
+  accepts?: (v: string) => boolean; // 보기 밖 값도 받는 질문(다른 목소리·곡 파일 경로) — 함수라 plan.json 에는 답만 남는다
+}
+
+export interface AnswerInput {
+  given?: Record<string, string | boolean | undefined>; // 명령 줄 opts 그대로 — --<flag> 값이 있으면 그 답
+  yes?: boolean;
+  noGen?: boolean;
+  allow?: Capability[] | null; // null 이면 --allow 를 안 줬다
+}
+
+export interface Settled {
+  answers: Record<string, string>;
+  open: Question[]; // 아직 사람이 골라야 하는 것
+  how: Record<string, "flag" | "no-gen" | "allow" | "yes">;
+}
+
+export function parseAllow(v: string | boolean | undefined): Capability[] | null {
+  if (typeof v !== "string") return null;
+  const list = v.split(",").map((s) => s.trim()).filter(Boolean);
+  const bad = list.filter((c) => !CAPABILITIES.includes(c as Capability));
+  if (bad.length) throw new Error(`--allow 는 ${CAPABILITIES.join("·")} 중에서 — ${bad.join(", ")}`);
+  return list as Capability[];
+}
+
+// 고르는 순서: 사람이 준 플래그 값 > --no-gen > --allow > --yes. 나머지는 묻는다 — 없는 능력(missing)은 플래그·생성 빼기만
+export function settle(questions: Question[], o: AnswerInput): Settled {
+  const out: Settled = { answers: {}, open: [], how: {} };
+  for (const q of questions) {
+    const given = o.given?.[q.flag.replace(/^--/, "")];
+    if (typeof given === "string" && (q.choices.some((c) => c.value === given) || q.accepts?.(given))) {
+      out.answers[q.id] = given;
+      out.how[q.id] = "flag";
+    } else if (q.missing) {
+      if (o.noGen && GENERATIVE.has(q.cap) && q.choices.some((c) => c.value === "none")) {
+        out.answers[q.id] = "none";
+        out.how[q.id] = "no-gen";
+      } else out.open.push(q);
+    } else if (o.noGen) {
+      out.answers[q.id] = q.skip;
+      out.how[q.id] = "no-gen";
+    } else if (o.allow) {
+      out.answers[q.id] = o.allow.includes(q.cap) ? q.default : q.skip;
+      out.how[q.id] = "allow";
+    } else if (o.yes) {
+      out.answers[q.id] = q.default;
+      out.how[q.id] = "yes";
+    } else out.open.push(q);
+  }
+  return out;
+}
+
+const usd = (n?: number) => (n === undefined ? "" : n === 0 ? " · 0원" : ` · 견적 $${n.toFixed(n < 0.1 ? 3 : 2)}`);
+
+function choiceLine(c: Choice, q: Question): string {
+  const tags = [c.value === q.default ? "권장" : "", c.value === q.skip && !q.missing ? "돈 안 듦" : ""].filter(Boolean);
+  return `${c.label}${usd(c.costUsd)}${tags.length ? ` (${tags.join("·")})` : ""}${c.note ? ` — ${c.note}` : ""}`;
+}
+
+// 터미널에서 한 번에 — 엔터만 치면 권장
+export async function askTerminal(questions: Question[]): Promise<Record<string, string> | null> {
+  if (!process.stdin.isTTY || !questions.length) return questions.length ? null : {};
+  const rl = createInterface({ input: process.stdin, output: process.stderr });
+  const out: Record<string, string> = {};
+  try {
+    process.stderr.write(`\n생성 전에 ${questions.length}가지를 정한다(엔터 = 권장)\n`);
+    for (const q of questions) {
+      const lines = q.choices.map((c, i) => `  ${i + 1}) ${choiceLine(c, q)}`).join("\n");
+      const a = (await rl.question(`\n${q.ask}\n${lines}\n번호: `)).trim();
+      out[q.id] = a === "" ? q.default : (q.choices[Number(a) - 1]?.value ?? q.default);
+    }
+  } finally {
+    rl.close();
+  }
+  return out;
+}
+
+// 터미널이 아닐 때 — 보기와 다시 부를 플래그를 찍는다(종료 코드 3 은 부르는 쪽이). 없는 능력은 자동 답 없이 여기서 멈춘다
+export function questionsText(questions: Question[]): string {
+  return questions
+    .map((q) => [`${q.ask}`, ...q.choices.map((c) => `  ${q.flag} ${c.value.padEnd(22)} ${choiceLine(c, q)}`)].join("\n"))
+    .join("\n\n");
+}
+
+// MAKE.md 맨 위 — AskUserQuestion 보기로 옮기기 좋게(질문·칩·보기 라벨·설명) + 답을 넣는 명령
+export function questionsMarkdown(questions: Question[], rerun: (flags: string) => string): string[] {
+  if (!questions.length) return [];
+  return [
+    "## 사용자에게 먼저 물을 것",
+    "",
+    "장면을 쓰기 전에 아래를 한 번에 묻는다(AskUserQuestion 한 번에 질문 여럿 — `header` 는 칩, 보기 첫째가 권장). 답은 같은 줄의 플래그 값으로 되돌려 준다:",
+    // AskUserQuestion 은 보기를 넷까지만 받는다 — 테마처럼 보기가 많은 질문은 나머지를 글로 보이고 Other 로 받는다
+    ...(questions.some((q) => q.choices.length > 4) ? ["보기가 넷을 넘는 질문은 첫 넷만 보기로 올리고, 나머지 보기 이름은 질문 글에 적어 「Other」로 받는다(보기 밖 값도 그 플래그로 받는다)."] : []),
+    "",
+    ...questions.flatMap((q) => [
+      `- **${q.ask}** (header: \`${q.header}\`, 플래그 \`${q.flag}\`)`,
+      ...q.choices.map((c) => `  - \`${c.value}\` — ${choiceLine(c, q)}`),
+    ]),
+    "",
+    `답을 받으면: \`${rerun(questions.map((q) => `${q.flag} <값>`).join(" "))}\``,
+    "",
+  ];
+}

package/packages/gen/src/audio.ts

@@ -0,0 +1,91 @@
+import { spawn } from "node:child_process";
+import { run } from "./media.ts";
+
+// 소리 다루기 — 목소리·곡 둘 다 여기 ffmpeg 한 벌로. 결과는 늘 48kHz 로 맞춰 섞을 때 다시 바꾸지 않는다
+const ff = (args: string[]) => run("ffmpeg", ["-v", "error", "-y", ...args]);
+
+export async function duration(path: string): Promise<number> {
+  const out = await run("ffprobe", ["-v", "error", "-show_entries", "format=duration", "-of", "default=nw=1:nk=1", path]);
+  const d = Number(out.toString().trim());
+  if (!Number.isFinite(d)) throw new Error(`길이를 못 읽음: ${path}`);
+  return d;
+}
+
+// 머리 없는 PCM(Gemini l16·DashScope 일부)을 wav 로 감싼다
+export function pcmToWav(pcm: Uint8Array, rate = 24000, channels = 1): Uint8Array {
+  const h = Buffer.alloc(44);
+  h.write("RIFF", 0);
+  h.writeUInt32LE(36 + pcm.length, 4);
+  h.write("WAVEfmt ", 8);
+  h.writeUInt32LE(16, 16);
+  h.writeUInt16LE(1, 20);
+  h.writeUInt16LE(channels, 22);
+  h.writeUInt32LE(rate, 24);
+  h.writeUInt32LE(rate * channels * 2, 28);
+  h.writeUInt16LE(channels * 2, 32);
+  h.writeUInt16LE(16, 34);
+  h.write("data", 36);
+  h.writeUInt32LE(pcm.length, 40);
+  return Buffer.concat([h, Buffer.from(pcm)]);
+}
+
+export interface Silence {
+  from: number;
+  to: number;
+}
+
+// 말 사이 숨 — 자막 마디를 이 자리에 붙인다(기본 -38dB 아래 0.12초 넘게).
+// silencedetect 는 결과를 stderr 로만 낸다 — run 은 stderr 를 버리니 따로 띄운다
+export async function findSilences(path: string, o: { db?: number; min?: number } = {}): Promise<Silence[]> {
+  const text = await new Promise<string>((resolve, reject) => {
+    const p = spawn("ffmpeg", ["-hide_banner", "-nostats", "-i", path, "-af", `silencedetect=noise=${o.db ?? -38}dB:d=${o.min ?? 0.12}`, "-f", "null", "-"]);
+    let err = "";
+    p.stderr.on("data", (b: Buffer) => (err += b));
+    p.on("error", reject);
+    p.on("close", (code) => (code === 0 ? resolve(err) : reject(new Error(`무음 찾기 실패(${code})`))));
+  });
+  const out: Silence[] = [];
+  let open: number | null = null;
+  for (const line of text.split("\n")) {
+    const s = line.match(/silence_start: (-?[\d.]+)/);
+    if (s) open = Math.max(0, Number(s[1]));
+    const e = line.match(/silence_end: ([\d.]+)/);
+    if (e && open !== null) {
+      out.push({ from: open, to: Number(e[1]) });
+      open = null;
+    }
+  }
+  if (open !== null) out.push({ from: open, to: Infinity });
+  return out;
+}
+
+// 앞뒤 무음을 깎은 구간 — 공급자마다 머리·꼬리 숨 길이가 달라 장면 길이가 흔들린다
+export async function voicedSpan(path: string): Promise<{ from: number; to: number; total: number }> {
+  const total = await duration(path);
+  const sil = await findSilences(path, { db: -45, min: 0.05 });
+  const head = sil.find((s) => s.from <= 0.01);
+  const tail = sil.find((s) => s.to === Infinity || s.to >= total - 0.01);
+  const from = head ? Math.min(head.to, total) : 0;
+  const to = tail && tail.from > from ? tail.from : total;
+  return { from, to, total };
+}
+
+// 48kHz 모노 wav 로 — 자르고(from..to) 빠르기(tempo, 0.9–1.1)를 바꾼다. 빠르기는 높이를 지키는 atempo
+export async function cutVoice(src: string, dst: string, o: { from: number; to: number; tempo?: number }): Promise<void> {
+  const tempo = o.tempo ?? 1;
+  if (tempo < 0.9 - 1e-6 || tempo > 1.1 + 1e-6) throw new Error(`목소리 빠르기는 0.9–1.1 안에서만: ${tempo}`);
+  const af = [`atrim=start=${o.from.toFixed(4)}:end=${o.to.toFixed(4)}`, "asetpts=PTS-STARTPTS", ...(Math.abs(tempo - 1) > 1e-4 ? [`atempo=${tempo.toFixed(4)}`] : []), "aresample=48000"].join(",");
+  await ff(["-i", src, "-af", af, "-ac", "1", "-c:a", "pcm_s16le", dst]);
+}
+
+// 장면 시각에 목소리 조각을 깔아 영상 길이 한 줄로
+export async function layVoices(clips: { file: string; at: number }[], total: number, dst: string): Promise<void> {
+  if (!clips.length) {
+    await ff(["-f", "lavfi", "-i", `anullsrc=r=48000:cl=mono`, "-t", total.toFixed(4), "-c:a", "pcm_s16le", dst]);
+    return;
+  }
+  const inputs = clips.flatMap((c) => ["-i", c.file]);
+  const chains = clips.map((c, i) => `[${i}]adelay=${Math.round(c.at * 1000)}:all=1[v${i}]`);
+  const mix = `${clips.map((_, i) => `[v${i}]`).join("")}amix=inputs=${clips.length}:normalize=0:dropout_transition=0,apad,atrim=0:${total.toFixed(4)}[out]`;
+  await ff([...inputs, "-filter_complex", [...chains, mix].join(";"), "-map", "[out]", "-ac", "1", "-ar", "48000", "-c:a", "pcm_s16le", dst]);
+}

package/packages/gen/src/blender.ts

@@ -0,0 +1,54 @@
+import { spawnSync } from "node:child_process";
+import { existsSync, readdirSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+// Blender 를 바깥 프로그램으로 찾기만 한다(bpy 를 가져오지 않는다) — kf blender 와 생성 능력 목록이 같은 답을 본다
+export const BLENDER_MIN = [4, 3]; // Grease Pencil v3(라인아트가 일반 모디파이어)가 4.3 부터
+
+// bpy 를 쓰는 헬퍼는 GPL 로 갈라 둔 tools/blender — npm 묶음에는 없어 KF_BLENDER_LIB 로 가리킨다
+export function blenderLibDir(): string {
+  return process.env.KF_BLENDER_LIB ? resolve(process.env.KF_BLENDER_LIB) : fileURLToPath(new URL("../../../tools/blender/", import.meta.url));
+}
+
+export const hasBlenderLib = (dir = blenderLibDir()): boolean => existsSync(join(dir, "run.py")) && existsSync(join(dir, "kfb.py"));
+
+function candidates(given?: string): string[] {
+  const out: string[] = [];
+  if (given) out.push(given);
+  if (process.env.BLENDER) out.push(process.env.BLENDER);
+  const which = spawnSync(process.platform === "win32" ? "where" : "which", ["blender"], { encoding: "utf8" });
+  if (which.status === 0) out.push(...which.stdout.split(/\r?\n/).filter(Boolean));
+  if (process.platform === "darwin") {
+    const apps = existsSync("/Applications") ? readdirSync("/Applications").filter((n) => /^Blender.*\.app$/.test(n)) : [];
+    // 이름에 판 번호를 붙여 여러 개 깔아 둔 기계면 높은 판부터
+    apps.sort((a, b) => b.localeCompare(a, undefined, { numeric: true }));
+    out.push(...apps.map((a) => `/Applications/${a}/Contents/MacOS/Blender`));
+  }
+  if (process.platform === "win32") {
+    const base = "C:\\Program Files\\Blender Foundation";
+    if (existsSync(base)) {
+      const dirs = readdirSync(base).sort((a, b) => b.localeCompare(a, undefined, { numeric: true }));
+      out.push(...dirs.map((d) => join(base, d, "blender.exe")));
+    }
+  }
+  return out;
+}
+
+export function findBlender(given?: string, warn: (line: string) => void = () => {}): { exe: string; version: number[] } {
+  const tried: string[] = [];
+  for (const exe of candidates(given)) {
+    if (tried.includes(exe)) continue;
+    tried.push(exe);
+    const r = spawnSync(exe, ["--version"], { encoding: "utf8", timeout: 30_000 });
+    const m = /Blender (\d+)\.(\d+)(?:\.(\d+))?/.exec(r.stdout ?? "");
+    if (r.status !== 0 || !m) continue;
+    const version = [Number(m[1]), Number(m[2]), Number(m[3] ?? 0)];
+    if (version[0] < BLENDER_MIN[0] || (version[0] === BLENDER_MIN[0] && version[1] < BLENDER_MIN[1])) {
+      warn(`${exe} 는 ${version.join(".")} — ${BLENDER_MIN.join(".")} 이상이 필요해 건너뛴다`);
+      continue;
+    }
+    return { exe, version };
+  }
+  throw new Error(`Blender ${BLENDER_MIN.join(".")} 이상을 못 찾았다 — --blender <실행 파일> 또는 BLENDER=<경로>. 본 곳: ${tried.join(", ") || "(없음)"}`);
+}

package/packages/gen/src/capabilities.ts

@@ -0,0 +1,151 @@
+import { existsSync, readdirSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import type { Capability } from "./ask.ts";
+import { blenderLibDir, findBlender, hasBlenderLib } from "./blender.ts";
+import { estimateImageUsd } from "./generate.ts";
+import { codexBin } from "./image/codex.ts";
+import { findKey, hasKey, whereToPut } from "./keys.ts";
+import { musicGenCapabilities } from "./music/index.ts";
+import { imageProviders, providerReady, videoProviders } from "./registry.ts";
+import { voiceCapabilities } from "./tts/index.ts";
+
+// 생성 능력 한 칸 — 무엇으로 만드는지·지금 쓸 수 있는지·한 번에 얼마인지·어디에 써도 되는지
+export interface CapabilityProvider {
+  cap: Capability;
+  id: string;
+  label: string;
+  ready: boolean;
+  detail: string; // 왜 되는지·안 되는지
+  fix?: string; // 안 될 때 켜는 법
+  unitUsd: number; // 한 번(그림 한 장·5초 영상 하나·샷 하나) 견적
+  unit: string;
+  license: string;
+  // 회사·바깥 결과물에 걸리는 제한 — 묻는 글과 자산 메타·결과 메타에 같이 남긴다
+  restrict?: string;
+}
+
+export interface CapabilityReport {
+  cap: Capability;
+  label: string;
+  providers: CapabilityProvider[];
+  best: CapabilityProvider | null; // 쓸 수 있는 것 중 권장(싼 것 먼저, 제한 없는 것 먼저)
+}
+
+const LABEL: Record<Capability, string> = {
+  image: "그림",
+  video: "영상 모델",
+  blender: "3D 샷(Blender)",
+  three: "3D 전환·화면 속 3D(three.js)",
+  music: "음악",
+  voice: "목소리(TTS)",
+  beats: "박자 분석(librosa)",
+  lyrics: "가사(JIZURA 가사 층·정렬)",
+  theme: "테마",
+};
+
+async function reach(url: string, init: RequestInit = {}, ms = 3000): Promise<number | string> {
+  try {
+    const r = await fetch(url, { ...init, signal: AbortSignal.timeout(ms) });
+    return r.status;
+  } catch (e) {
+    return e instanceof Error ? e.name === "TimeoutError" ? "응답 없음" : e.message.slice(0, 60) : String(e);
+  }
+}
+
+// probe 면 키·주소가 실제로 사는지 가볍게 두드린다(OG 모델 목록·H3 서버) — 돈이 드는 호출은 하지 않는다
+async function images(probe: boolean): Promise<CapabilityProvider[]> {
+  const est = estimateImageUsd({ prompt: "", size: "1920x1080", quality: "high" });
+  let og: { ok: boolean; why: string } = { ok: hasKey("opengateway"), why: hasKey("opengateway") ? "키 있음" : "키 없음" };
+  if (og.ok && probe) {
+    const s = await reach(`${process.env.KF_OG_HOST ?? "https://apis.opengateway.ai"}/v1/models`, { headers: { Authorization: `Bearer ${findKey("opengateway")}` } });
+    og = s === 200 ? { ok: true, why: "키 살아 있음(모델 목록 200)" } : { ok: false, why: `키는 있는데 OG 가 ${s}${s === 401 ? "(키가 틀렸다)" : s === 402 ? "(잔액 부족)" : ""}` };
+  }
+  const out: CapabilityProvider[] = [];
+  for (const p of imageProviders()) {
+    if (p.id === "codex-imagegen") {
+      const bin = codexBin();
+      const ready = providerReady(p);
+      out.push({
+        cap: "image", id: p.id, label: "codex imagegen(ChatGPT 요금제)", ready,
+        detail: !bin ? "codex CLI 없음" : ready ? "로그인 됨 — 한 장 1–2분" : "codex 는 있는데 로그인 안 됨",
+        fix: !bin ? "npm i -g @openai/codex && codex login" : ready ? undefined : "codex login",
+        unitUsd: 0, unit: "장", license: p.license,
+      });
+      continue;
+    }
+    // 같은 키·같은 단가인 OG 모델 셋은 기본만 앞에 세우고 나머지는 같은 판정으로 둔다
+    out.push({ cap: "image", id: p.id, label: `OG ${p.model}`, ready: og.ok, detail: og.why, fix: og.ok ? undefined : whereToPut("opengateway"), unitUsd: est, unit: "1920x1080 high 한 장", license: p.license });
+  }
+  return out;
+}
+
+async function videos(probe: boolean): Promise<CapabilityProvider[]> {
+  const sample = { prompt: "", duration: 5, aspect: "16:9", firstFrame: "x", lastFrame: "y", resolution: "720p" };
+  const out: CapabilityProvider[] = [];
+  for (const p of videoProviders()) {
+    let ready = providerReady(p);
+    let detail = ready ? "키 있음(키만 봄)" : "키 없음";
+    if (p.id === "h3-pod") {
+      const url = findKey("h3");
+      if (!url) detail = "KF_H3_URL 없음";
+      else if (!process.env.KF_H3_STEPS) {
+        ready = false;
+        detail = "KF_H3_STEPS 없음(터보 LoRA 면 9, 없으면 50 — 파드 운영자에게)";
+      } else if (probe) {
+        const s = await reach(`${url.replace(/\/+$/, "")}/v1/models`);
+        ready = s === 200;
+        detail = ready ? "서버 살아 있음" : `서버가 ${s}`;
+      } else detail = "주소 있음(두드려 보지 않음)";
+    }
+    out.push({
+      cap: "video", id: p.id, label: p.model, ready, detail,
+      fix: ready ? undefined : p.id === "h3-pod" ? "KF_H3_URL=<SGLang 주소> KF_H3_STEPS=<9|50>" : whereToPut(p.keyName),
+      unitUsd: p.estimateUsd(sample), unit: "5초 720p 첫+끝 프레임", license: p.license, restrict: p.restrict,
+    });
+  }
+  return out;
+}
+
+function blender(): CapabilityProvider {
+  const lib = blenderLibDir();
+  const base = { cap: "blender" as const, id: "blender", label: "Blender 툰 3D(kf blender)", unitUsd: 0, unit: "샷 하나(로컬 렌더)", license: "Blender GPL — 굽힌 그림·영상은 만든 사람 것, 헬퍼(tools/blender)는 GPL-3.0 로 npm 묶음 밖" };
+  if (!hasBlenderLib(lib)) return { ...base, ready: false, detail: `헬퍼 없음: ${lib}`, fix: "레포의 tools/blender 를 받아 KF_BLENDER_LIB=<그 폴더>" };
+  try {
+    const b = findBlender();
+    return { ...base, ready: true, detail: `Blender ${b.version.join(".")} — 1920x1080 한 장 0.3–0.4초(M 맥)` };
+  } catch (e) {
+    return { ...base, ready: false, detail: (e instanceof Error ? e.message : String(e)).split(" — ")[0], fix: process.platform === "darwin" ? "brew install --cask blender (4.3 이상)" : "blender.org 에서 4.3 이상" };
+  }
+}
+
+// three.js 는 레포 안 의존성이라 늘 있다 — 렌더 크롬이 CanvasDrawElement 로 살아 있는 장면을 텍스처로 올린다
+function three(): CapabilityProvider[] {
+  const license = "three.js MIT";
+  return [
+    { cap: "three", id: "transition3d", label: "3D 전환(이음매 장면 — dive·portal·cards·shatter·zoomOut·fold)", ready: true, detail: "레포 안", unitUsd: 0, unit: "전환 하나", license },
+    { cap: "three", id: "stage3d", label: "화면 속 3D(입체 테마 무대)", ready: true, detail: "레포 안", unitUsd: 0, unit: "장면 하나", license },
+  ];
+}
+
+const musicDir = (): string => process.env.KF_MUSIC_DIR || fileURLToPath(new URL("../../../music/", import.meta.url));
+
+// 곡 모음만 여기서 센다 — 생성 음악·목소리 공급자는 목소리·음악 담당(src/music·src/tts)이 같은 꼴로 더한다
+function music(): CapabilityProvider[] {
+  const dir = musicDir();
+  const songs = existsSync(dir) ? readdirSync(dir).filter((f) => /\.(mp3|wav|m4a|aac|flac|ogg)$/i.test(f)) : [];
+  return [{ cap: "music", id: "library", label: "곡 모음", ready: songs.length > 0, detail: songs.length ? `${songs.length}곡(${dir})` : `비었다: ${dir}`, fix: songs.length ? undefined : "KF_MUSIC_DIR=<곡 폴더> 또는 --music 곡", unitUsd: 0, unit: "곡", license: "곡마다 music/README.md" }];
+}
+
+export async function capabilities(o: { probe?: boolean } = {}): Promise<CapabilityReport[]> {
+  const probe = o.probe ?? false;
+  const [img, vid] = await Promise.all([images(probe), videos(probe)]);
+  const all: CapabilityProvider[] = [...img, ...vid, blender(), ...three(), ...music(), ...voiceCapabilities(), ...musicGenCapabilities()];
+  return (["image", "video", "blender", "three", "music", "voice"] as Capability[]).map((cap) => {
+    const providers = all.filter((p) => p.cap === cap);
+    // 그림은 목록 순서(OG 기본 — 빠르고 실측된 길)가 권장, codex 는 0원 대안. 나머지는 제한 없는 것·싼 것 먼저
+    const usable = providers
+      .filter((p) => p.ready)
+      .sort((a, b) => Number(!!a.restrict) - Number(!!b.restrict) || (cap === "image" ? providers.indexOf(a) - providers.indexOf(b) : a.unitUsd - b.unitUsd));
+    return { cap, label: LABEL[cap], providers, best: usable[0] ?? null };
+  });
+}

package/packages/gen/src/generate.ts

@@ -0,0 +1,206 @@
+import { createHash } from "node:crypto";
+import { copyFileSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, join } from "node:path";
+import { chromaKey, fitImage, KEY_BG, probe, transparentRatio } from "./media.ts";
+import { apiSize } from "./image/og.ts";
+import { pickImage, pickVideo } from "./registry.ts";
+import type { Asset, AssetKind, AssetMeta, ImageProvider, ImageRequest, ProviderInfo, RawResult, VideoRequest } from "./types.ts";
+
+export interface GenContext {
+  outDir: string; // 보통 <proj>/assets/gen
+  cacheDir?: string;
+  maxUsd?: number; // 영상 하나 상한
+  imageMaxUsd?: number; // 그림 한 장 상한
+  approve?: boolean; // 영상은 이게 true 일 때만 돈을 쓴다
+  log?: (line: string) => void;
+}
+
+export const DEFAULT_MAX_USD = 1;
+export const DEFAULT_IMAGE_MAX_USD = 0.25;
+
+// 돈을 쓰기 전에 멈춘 이유. CLI 는 이걸 보고 종료 코드 3 과 견적을 낸다.
+export class NeedsApproval extends Error {
+  estimateUsd: number;
+  provider: string;
+  constructor(provider: string, estimateUsd: number, why: string) {
+    super(`${why} — ${provider} 견적 $${estimateUsd.toFixed(3)}`);
+    this.provider = provider;
+    this.estimateUsd = estimateUsd;
+  }
+}
+
+export function cacheDir(ctx: GenContext): string {
+  return ctx.cacheDir ?? process.env.KF_GEN_CACHE ?? join(homedir(), ".cache", "kasaframe", "gen");
+}
+
+function stable(v: unknown): unknown {
+  if (Array.isArray(v)) return v.map(stable);
+  if (v && typeof v === "object") {
+    return Object.fromEntries(
+      Object.keys(v)
+        .filter((k) => (v as any)[k] !== undefined)
+        .sort()
+        .map((k) => [k, stable((v as any)[k])]),
+    );
+  }
+  return v;
+}
+
+export function sha256(data: Uint8Array | string): string {
+  return createHash("sha256").update(data).digest("hex");
+}
+
+// 입력 파일은 경로가 아니라 내용으로 센다 — 같은 그림을 다른 곳에 두어도 같은 결과를 다시 쓴다.
+export function cacheKey(kind: AssetKind, p: ProviderInfo, req: object, inputs: { role: string; sha256: string }[]): string {
+  const r: Record<string, unknown> = { ...req };
+  for (const k of ["refs", "firstFrame", "lastFrame"]) delete r[k];
+  return sha256(JSON.stringify(stable({ kind, provider: p.id, model: p.model, variant: p.variant, req: r, inputs })));
+}
+
+function inputsOf(req: { refs?: string[]; firstFrame?: string; lastFrame?: string }): { role: string; sha256: string }[] {
+  const list: { role: string; path: string }[] = [
+    ...(req.refs ?? []).map((path, i) => ({ role: `ref${i}`, path })),
+    ...(req.firstFrame ? [{ role: "first", path: req.firstFrame }] : []),
+    ...(req.lastFrame ? [{ role: "last", path: req.lastFrame }] : []),
+  ];
+  return list.map(({ role, path }) => {
+    if (!existsSync(path)) throw new Error(`입력 파일 없음: ${path}`);
+    return { role, sha256: sha256(readFileSync(path)) };
+  });
+}
+
+// 1024x1024 출력 토큰(OpenAI 계산기, 2.5 계열). 실제 비용은 응답 usage 로 다시 적는다.
+const IMAGE_TOKENS: Record<string, number> = { low: 196, medium: 439, high: 1756, xhigh: 3122, max: 7024, auto: 1756 };
+
+export function estimateImageUsd(req: ImageRequest): number {
+  const { w, h } = apiSize(req.size);
+  const out = (IMAGE_TOKENS[req.quality ?? "high"] ?? 1756) * ((w * h) / 1_048_576) * 30e-6;
+  const refs = (req.refs?.length ?? 0) * 1024 * 8e-6;
+  return out + refs;
+}
+
+function fromCache(id: string, key: string, ctx: GenContext): Asset | null {
+  const dir = cacheDir(ctx);
+  const metaPath = join(dir, `${key}.json`);
+  if (!existsSync(metaPath)) return null;
+  const meta = JSON.parse(readFileSync(metaPath, "utf8")) as AssetMeta;
+  const src = join(dir, meta.file);
+  if (!existsSync(src)) return null;
+  mkdirSync(ctx.outDir, { recursive: true });
+  const file = `${id}.${meta.file.split(".").pop()}`;
+  const path = join(ctx.outDir, file);
+  if (!existsSync(path) || sha256(readFileSync(path)) !== sha256(readFileSync(src))) copyFileSync(src, path);
+  const out = { ...meta, id, file };
+  writeFileSync(join(ctx.outDir, `${id}.json`), JSON.stringify(out, null, 2) + "\n");
+  return { path, meta: out, cached: true };
+}
+
+async function store(
+  id: string,
+  kind: AssetKind,
+  key: string,
+  p: ProviderInfo,
+  prompt: string,
+  raw: RawResult,
+  tmpPath: string,
+  inputs: AssetMeta["inputs"],
+  elapsedMs: number,
+  ctx: GenContext,
+): Promise<Asset> {
+  const dir = cacheDir(ctx);
+  const ext = tmpPath.split(".").pop()!;
+  const cached = join(dir, `${key}.${ext}`);
+  renameSync(tmpPath, cached);
+  const pr = await probe(cached);
+  const meta: AssetMeta = {
+    id,
+    kind,
+    file: basename(cached),
+    provider: p.id,
+    model: raw.model,
+    prompt,
+    seed: raw.seed,
+    params: raw.params,
+    inputs,
+    costUsd: Number(raw.costUsd.toFixed(5)),
+    costEstimated: raw.costEstimated,
+    elapsedMs,
+    license: p.license,
+    region: p.region,
+    ...(p.restrict ? { restrict: p.restrict } : {}),
+    cacheKey: key,
+    createdAt: new Date().toISOString(),
+    width: pr.width,
+    height: pr.height,
+    ...(kind === "vid" ? { duration: pr.duration, fps: pr.fps } : {}),
+    ...(raw.notes?.length ? { notes: raw.notes } : {}),
+  };
+  writeFileSync(join(dir, `${key}.json`), JSON.stringify(meta, null, 2) + "\n");
+  return { ...fromCache(id, key, ctx)!, cached: false };
+}
+
+async function makeImage(p: ImageProvider, req: ImageRequest, tmp: string): Promise<RawResult> {
+  const call = (r: ImageRequest) => (r.refs?.length && p.edit ? p.edit(r) : p.generate(r));
+  let raw = await call(req);
+  writeFileSync(tmp, raw.bytes);
+  if (req.transparent) {
+    if (raw.notes?.includes("chroma-key")) {
+      await chromaKey(tmp, tmp);
+    } else if ((await transparentRatio(tmp)) < 0.005) {
+      // 투명을 받는다던 모델이 불투명하게 돌려줬다 — 한 장 더 써서 단색 바탕 + 키잉으로 간다.
+      const again = await call({ ...req, prompt: `${req.prompt}\n\n${KEY_BG}`, transparent: false });
+      writeFileSync(tmp, again.bytes);
+      await chromaKey(tmp, tmp);
+      raw = { ...again, costUsd: raw.costUsd + again.costUsd, notes: [...(again.notes ?? []), "alpha-failed", "chroma-key"] };
+    }
+  }
+  // 공급자마다 그리는 크기가 다르다(OG 는 16의 배수, codex 는 세 꼴) — 실제로 나온 크기를 재서 맞춘다
+  const { width: w, height: h } = await probe(tmp);
+  const [rw, rh] = req.size.split("x").map(Number);
+  if (w !== rw || h !== rh) {
+    await fitImage(tmp, tmp, rw, rh);
+    raw.notes = [...(raw.notes ?? []), `fit ${w}x${h}->${rw}x${rh}`];
+  }
+  return raw;
+}
+
+export async function genImage(id: string, req: ImageRequest, ctx: GenContext, providerId?: string): Promise<Asset> {
+  const p = pickImage(providerId);
+  const inputs = inputsOf(req);
+  const key = cacheKey("img", p, req, inputs);
+  const hit = fromCache(id, key, ctx);
+  if (hit) return hit;
+  const est = p.estimateUsd ? p.estimateUsd(req) : estimateImageUsd(req);
+  const cap = ctx.imageMaxUsd ?? DEFAULT_IMAGE_MAX_USD;
+  if (est > cap) throw new NeedsApproval(p.id, est, `그림 한 장 상한 $${cap} 초과`);
+  mkdirSync(cacheDir(ctx), { recursive: true });
+  const tmp = join(cacheDir(ctx), `.${key}.tmp.png`);
+  ctx.log?.(`그림 ${id}: ${p.id} 견적 $${est.toFixed(3)}`);
+  const t0 = Date.now();
+  const raw = await makeImage(p, req, tmp);
+  return store(id, "img", key, p, req.prompt, raw, tmp, inputs, Date.now() - t0, ctx);
+}
+
+export function planVideo(req: VideoRequest, ctx: GenContext, providerId?: string) {
+  const p = pickVideo(providerId, req);
+  const inputs = inputsOf(req);
+  const key = cacheKey("vid", p, req, inputs);
+  return { provider: p, inputs, key, estimateUsd: p.estimateUsd(req), cached: existsSync(join(cacheDir(ctx), `${key}.json`)) };
+}
+
+export async function genVideo(id: string, req: VideoRequest, ctx: GenContext, providerId?: string): Promise<Asset> {
+  const { provider: p, inputs, key, estimateUsd: est } = planVideo(req, ctx, providerId);
+  const hit = fromCache(id, key, ctx);
+  if (hit) return hit;
+  const cap = ctx.maxUsd ?? DEFAULT_MAX_USD;
+  if (est > cap) throw new NeedsApproval(p.id, est, `영상 하나 상한 $${cap} 초과`);
+  if (!ctx.approve) throw new NeedsApproval(p.id, est, "영상 생성은 승인(--yes)이 있어야 돌린다");
+  mkdirSync(cacheDir(ctx), { recursive: true });
+  ctx.log?.(`영상 ${id}: ${p.id} 견적 $${est.toFixed(3)} — 생성 중(몇십 초~몇 분)`);
+  const t0 = Date.now();
+  const raw = await p.generate(req);
+  const tmp = join(cacheDir(ctx), `.${key}.tmp.${raw.ext}`);
+  writeFileSync(tmp, raw.bytes);
+  return store(id, "vid", key, p, req.prompt, raw, tmp, inputs, Date.now() - t0, ctx);
+}