kasaframe 0.1.1 → 0.1.4

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

@@ -0,0 +1,110 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join, relative, resolve } from "node:path";
+import { listSeries, loadSeries, type Purpose, type Series, seriesDir, writeSeries } from "@kasaframe/plan";
+import { loadTheme } from "@kasaframe/themes";
+import type { Command } from "../command.ts";
+import { parseFlags } from "../command.ts";
+
+const USAGE = `kf series list
+kf series show <id>
+kf series new <id> --label "OG 쇼츠" --match "OG 쇼츠,OG shorts" --purpose shorts [--theme og-measure] [--voice gemini:Charon]
+              [--mood deep | --music music/x.mp3] [--captions on|off|none] [--duration 45-60] [--end-title 이름] [--end-line 한 줄]
+              [--answers image=og-gpt-image-2.5-sunburst,video=none] [--from <잘 나온 프로젝트 폴더>] [--force]
+
+시리즈 묶음(series/<id>.json, KF_SERIES_DIR 로 바꿈) — 요청이 match 의 말을 짚으면 kf make 가 묻지 않고 이 묶음대로 간다:
+용도·테마·목소리·곡(파일이면 늘 그 곡, 분위기면 곡 모음의 같은 곡)·자막·길이·끝 카드·생성 질문 답. 용도 규칙은 그 용도 틀이 정한다.
+--from 은 그 프로젝트의 plan.json·kf.json(용도·테마·목소리·곡·자막·길이·이름·고른 답)을 묶음으로 옮긴다 — 플래그가 이긴다.`;
+
+function range(v: string): { min: number; max: number; default: number } {
+  const m = /^(\d+(?:\.\d+)?)(?:-(\d+(?:\.\d+)?))?$/.exec(v);
+  if (!m) throw new Error(`--duration 은 45 또는 45-60 — ${v}`);
+  const min = Number(m[1]);
+  const max = Number(m[2] ?? m[1]);
+  return { min, max, default: min };
+}
+
+function fromProject(dir: string): Partial<Series> {
+  const plan = JSON.parse(readFileSync(join(dir, "plan.json"), "utf8"));
+  const kf = existsSync(join(dir, "kf.json")) ? JSON.parse(readFileSync(join(dir, "kf.json"), "utf8")) : {};
+  const answers: Record<string, string> = Object.fromEntries(Object.entries(plan.answers ?? {}).filter(([k, v]) => k !== "voice" && k !== "music" && typeof v === "string") as [string, string][]);
+  return {
+    purpose: plan.purpose,
+    ...(plan.theme ? { theme: plan.theme } : { style: plan.style }),
+    ...(plan.voice ? { voice: plan.voice } : {}),
+    ...(plan.mood ? { music: { mood: plan.mood } } : {}),
+    captions: kf.captions ?? plan.captions,
+    duration: { min: plan.duration, max: plan.duration, default: plan.duration },
+    end: { title: plan.title },
+    ...(Object.keys(answers).length ? { answers } : {}),
+  };
+}
+
+function show(s: Series): string {
+  const warn: string[] = [];
+  if (s.theme) {
+    try {
+      const t = loadTheme(s.theme);
+      if (t.status !== "approved") warn.push(`테마 ${s.theme} 는 ${t.status} — 승인 전`);
+      if (!t.purposes.includes(s.purpose)) warn.push(`테마 ${s.theme} 의 용도에 ${s.purpose} 가 없다`);
+    } catch (e) {
+      warn.push(`테마 ${s.theme}: ${e instanceof Error ? e.message : e}`);
+    }
+  }
+  return [JSON.stringify(s, null, 2), ...warn.map((w) => `주의: ${w}`)].join("\n");
+}
+
+const cmd: Command = {
+  summary: "시리즈 묶음 — 짚으면 묻지 않고 매번 같은 용도·테마·목소리·곡·자막·길이·끝 카드",
+  usage: USAGE,
+  async run(argv) {
+    const [sub, ...rest] = argv;
+    const { args, opts } = parseFlags(rest);
+    const str = (k: string) => (typeof opts[k] === "string" ? (opts[k] as string) : undefined);
+    if (sub === "list") {
+      const all = listSeries();
+      if (!all.length) console.log(`시리즈 없음 — kf series new 로 (${seriesDir()})`);
+      for (const s of all) console.log(`${s.id.padEnd(16)} ${s.label} · ${s.purpose}${s.theme ? ` · 테마 ${s.theme}` : ""}${s.voice ? ` · ${s.voice}` : ""} — 「${s.match.join("」「")}」`);
+      return 0;
+    }
+    if (sub === "show" && args[0]) {
+      console.log(show(loadSeries(args[0])));
+      return 0;
+    }
+    if (sub === "new" && args[0]) {
+      const id = args[0];
+      if (existsSync(join(seriesDir(), `${id}.json`)) && !opts.force) {
+        console.error(`kf series new: ${id} 가 이미 있다 — 덮으려면 --force`);
+        return 2;
+      }
+      const base: Partial<Series> = str("from") ? fromProject(resolve(str("from")!)) : {};
+      const answers = str("answers") ? Object.fromEntries(str("answers")!.split(",").map((kv) => kv.split("=").map((x) => x.trim()) as [string, string])) : undefined;
+      const s: Series = {
+        ...base,
+        id,
+        label: str("label") ?? base.label ?? id,
+        match: str("match") ? str("match")!.split(",").map((x) => x.trim()).filter(Boolean) : (base.match ?? []),
+        purpose: (str("purpose") ?? base.purpose) as Purpose,
+        ...(str("theme") ? { theme: str("theme") } : {}),
+        ...(str("voice") ? { voice: str("voice") } : {}),
+        ...(str("music") ? { music: { file: str("music") } } : str("mood") ? { music: { mood: str("mood") } } : {}),
+        ...(str("captions") ? { captions: str("captions") as Series["captions"] } : {}),
+        ...(str("duration") ? { duration: range(str("duration")!) } : {}),
+        ...(str("end-title") || str("end-line") ? { end: { ...base.end, ...(str("end-title") ? { title: str("end-title") } : {}), ...(str("end-line") ? { line: str("end-line") } : {}) } } : {}),
+        ...(answers ? { answers: { ...base.answers, ...answers } } : {}),
+      };
+      try {
+        // 사람이 열어 볼 파일이라 이름·짚는 말·용도를 맨 위에
+        const { id: _, label, match, purpose, ...rest } = s;
+        const file = writeSeries({ id, label, match, purpose, ...rest });
+        console.log(`${relative(process.cwd(), file) || file}\n${show(s)}`);
+        return 0;
+      } catch (e) {
+        console.error(`kf series new: ${e instanceof Error ? e.message : e}`);
+        return 2;
+      }
+    }
+    console.error(USAGE);
+    return 2;
+  },
+};
+export default cmd;

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

@@ -1,5 +1,8 @@
 import { spawnSync } from "node:child_process";
-import { existsSync } from "node:fs";
+import { chmodSync, existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { createInterface } from "node:readline";
+import { keyFile } from "@kasaframe/gen";
 import { platform } from "node:os";
 import { fileURLToPath } from "node:url";
 import { beatsVenv, checks, playwrightCli, report, requirements, venvPython } from "../deps.ts";
@@ -28,25 +31,61 @@ function beats(): boolean {
   return step("librosa", venvPython(beatsVenv), ["-m", "pip", "install", "-r", requirements]);
 }
 
-// 고정 커밋을 받아 묶고 한글 글꼴을 받는다(비동기라 따로 돌린다). 일본어 가사는 node packages/jizura/src/install.ts --lang ko,ja
+// 엔진·자주 쓰는 한글 글꼴은 패키지에 실려 있어 받을 것은 나머지 얼굴뿐이다(처음 쓸 때도 받는다 — 오프라인으로 구울 기계면 미리). 일본어 가사는 node packages/jizura/src/install.ts --lang ko,ja
 const jizura = () => step("JIZURA", process.execPath, [fileURLToPath(import.meta.resolve("@kasaframe/jizura/install")), "--lang", "ko"]);
 
 // 이름 하나 = 깔 것 하나. 이름 없이 부르면 DEFAULT 만
 const STEPS: Record<string, { what: string; run: () => boolean }> = {
   chrome: { what: "Playwright 크롬(chromium) — 렌더·검사", run: chrome },
   beats: { what: `librosa(${beatsVenv}) — 곡 분석 kf beats`, run: beats },
-  jizura: { what: "JIZURA 가사 층 엔진(고정 커밋)·한글 글꼴 60MB(~/.cache/kasaframe/jizura) — 뮤비 가사 키네틱", run: jizura },
+  jizura: { what: "JIZURA 가사 층의 나머지 한국어 글꼴 17MB(~/.cache/kasaframe/jizura) — 엔진·자주 쓰는 글꼴은 실려 있고 이것도 처음 쓸 때 받는다, 오프라인으로 구울 기계면 미리", run: jizura },
   lyrics: { what: "demucs·stable-ts(~/.cache/kasaframe/py/lyrics, 2GB 안팎) — kf lyrics align", run: setupLyrics },
 };
 const DEFAULT = ["chrome", "beats"];
 
+// 키는 화면·셸 기록에 남지 않게 — 터미널이면 입력을 가리고, 아니면 표준 입력 한 줄로 받는다. 값은 찍지 않는다
+function readSecret(prompt: string): Promise<string> {
+  return new Promise((done) => {
+    const rl = createInterface({ input: process.stdin, output: process.stderr, terminal: !!process.stdin.isTTY });
+    if (process.stdin.isTTY) {
+      process.stderr.write(prompt);
+      (rl as unknown as { _writeToOutput: (s: string) => void })._writeToOutput = () => {};
+    }
+    rl.once("line", (line) => {
+      rl.close();
+      if (process.stdin.isTTY) process.stderr.write("\n");
+      done(line.trim());
+    });
+  });
+}
+
+async function key(name: string | undefined): Promise<number> {
+  if (!name || !/^[a-z0-9-]+$/.test(name)) {
+    console.error("kf setup key <이름> — opengateway · fal · gemini · minimax · ltx · elevenlabs · dashscope (kf doctor 「생성 능력」이 무엇이 없는지 알려 준다)");
+    return 2;
+  }
+  const value = await readSecret(`${name} 키(입력은 안 보인다): `);
+  if (!value) {
+    console.error("kf setup key: 빈 값 — 아무것도 쓰지 않았다");
+    return 2;
+  }
+  const file = keyFile(name);
+  mkdirSync(dirname(file), { recursive: true });
+  writeFileSync(file, `${value}\n`, { mode: 0o600 });
+  chmodSync(file, 0o600);
+  console.log(`${file} 에 썼다(600). 확인: kf doctor`);
+  return 0;
+}
+
 const cmd: Command = {
   summary: "바깥 도구 깔기 — Playwright 크롬·librosa. ffmpeg 는 시스템 패키지라 깔 명령만 알린다",
   usage: `kf setup [이름…]   이름 없이: ${DEFAULT.join(" ")}
+kf setup key <이름>   생성 공급자 키를 숨겨 받아 ~/.config/kasaframe/keys/<이름>(600)에 — 값은 찍지 않는다
 ${Object.entries(STEPS).map(([k, s]) => `  ${k.padEnd(8)} ${s.what}`).join("\n")}
   kf beats 는 KF_PYTHON 이 없으면 위 venv 를 먼저 쓴다. 끝에 kf doctor 와 같은 표를 찍는다`,
   async run(argv) {
     const { args } = parseFlags(argv);
+    if (args[0] === "key") return key(args[1]);
     const names = args.length ? args : DEFAULT;
     const unknown = names.filter((n) => !STEPS[n]);
     if (unknown.length) {

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

@@ -1,8 +1,14 @@
 import { spawnSync } from "node:child_process";
-import { join } from "node:path";
-import { listThemes, themesDir } from "@kasaframe/themes";
+import { copyFileSync, existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { type Aspect, PURPOSES, type Purpose, suggestThemes } from "@kasaframe/plan";
+import { cellPath, cellsDir, listThemes, listVariants, loadTheme, sheetDir, type Theme, themeDims, themeSample, themesDir } from "@kasaframe/themes";
 import { briefs, review, scaffold, sessionPrompt, setStatus, staticCheck } from "@kasaframe/themes/factory";
+import { launch } from "../browser.ts";
+import { cellFrame, cellOf, ensureCells, type GridCell, gridSheet, SAMPLE } from "../cells.ts";
 import { type Command, num, parseFlags } from "../command.ts";
+import { vary } from "../vary.ts";
 
 const kfBin = new URL("../kf.ts", import.meta.url).pathname;
 
@@ -13,6 +19,22 @@ kf theme new <id> --ref <그림·영상·폴더·URL> [--ref …] [--name 이름
 kf theme check <id> [--no-page]     계약·빈칸 검사 + kf check sample
 kf theme review <id> [--tabs 2]     굽기 → mp4 검사 → 장면 모음·대표 장면 → 공유 폴더 → status review
 kf theme approve <id>               사람이 견본을 보고 OK 한 뒤에만
+kf theme vary <세계|all> [--n 16] [--force] [--seed 글]
+                                    세계 하나에서 겉모습만 바꾼 변주를 기본 포함 n 개까지 — 색 조합(밝음·어두움)·글꼴 짝·질감·선·모서리·빠르기를
+                                    세계 theme.json vary 범위 안에서 섞고, 대비·의미색·색각 이상을 계산으로 거른 뒤 서로 먼 차례로 표준 장면에 입혀
+                                    kf check 를 넘고 이미 뽑은 판과 충분히 다른 것만 themes/<세계>/variants/<이름>.json 에 남긴다(입체 세계는 끝 구간만 검사).
+                                    이미 있으면 모자란 만큼만. all 은 approved 세계 전부. 끝에 그 세계 변주 격자
+kf theme sheet --variants <세계|all> [--share]
+                                    변주 격자 — 세계마다 기본+변주 한 장(<캐시>/theme-cells/<세계>/sheet.png), all 이면 전체 한 장(all.png)과
+                                    목록(변주목록.md)까지. 칸이 없거나 낡으면 그 자리에서 찍는다. --share 면 kasaterm 공유 폴더 kasaframe-테마-변주 로
+kf theme list [--variants [세계]]   세계 목록, --variants 면 변주까지
+kf theme suggest [--request 글] [--purpose ${PURPOSES.join("|")}] [--aspect 9:16|16:9|1:1] [--mood 글] [--use 낱말,…] [--n 4] [--json]
+                                    요청에 맞는 approved 세계·변주 후보 — kf make 의 테마 질문과 같은 고르기(요청 낱말·분위기 낱말·쓰임 낱말).
+                                    --json 이면 { candidates: [{ id, world, variant, name, dims, why, cell, sample }] } — cell 은 칸 캐시
+                                    그림(없으면 null), sample 은 묻기 보기에 붙일 견본(칸 → 견본 시트 칸 → 대표 장면)
+kf theme sheet [--out 파일.png]     approved 테마마다 같은 문장 한 장면(쇼츠 9:16)을 감독 모드로 짓고 검사를 거쳐, 장면 끝 프레임을
+                                    격자 한 장으로 — 이름·2D/3D 딱지, 안전 영역 점선. 기본 themes/_sheet/sheet.png, 칸은 그 옆 <id>.png
+                                    (kf make 의 테마 질문 보기가 이 칸을 견본으로 짚는다). 검사 오류가 남은 칸은 표시하고 종료 1
 
   new 는 themes/<id>/ 에 계약 파일 뼈대·refs/·브리프대로 자른 곡과 박·장면 넷 뼈대·THEME-MAKE.md(지시서)를 짓고,
   그 지시서를 받을 세션을 여는 명령을 알려 준다. 테마는 그 세션이 만든다.`,
@@ -20,12 +42,41 @@ kf theme approve <id>               사람이 견본을 보고 OK 한 뒤에만
     const [sub, ...rest] = argv;
     const { args, opts } = parseFlags(rest);
     const id = args[0];
+    if (sub === "sheet" && opts.variants) return variantSheets(typeof opts.variants === "string" ? opts.variants : (args[0] ?? "all"), !!opts.share);
+    if (sub === "sheet") return sheet(resolve(typeof opts.out === "string" ? opts.out : join(sheetDir, "sheet.png")));
     if (sub === "list" || !sub) {
-      const all = listThemes();
+      const only = typeof opts.variants === "string" ? opts.variants : args[0];
+      const all = listThemes({ variants: !!opts.variants }).filter((t) => !only || t.world === only);
       if (!all.length) console.log("(테마 없음)");
-      for (const t of all) console.log(`${t.id.padEnd(18)} ${t.status.padEnd(9)} ${String(t.approvedAt ?? "").padEnd(11)} 효과 ${String(t.effects.length).padStart(2)} · ${t.metaphor}`);
+      for (const t of all)
+        console.log(
+          t.variant
+            ? `  ${t.id.padEnd(34)} ${t.status.padEnd(9)} ${t.style.scheme.padEnd(5)} · ${t.variant.desc}`
+            : `${t.id.padEnd(18)} ${t.status.padEnd(9)} ${String(t.approvedAt ?? "").padEnd(11)} 효과 ${String(t.effects.length).padStart(2)}${opts.variants ? ` · 변주 ${listVariants(t.id).length}` : ""} · ${t.metaphor}`,
+        );
       return 0;
     }
+    if (sub === "suggest") return suggest(opts);
+    if (sub === "vary") {
+      if (!id) {
+        console.error("kf theme vary: 세계 id 나 all 을 준다");
+        return 2;
+      }
+      const worlds = id === "all" ? listThemes({ status: "approved" }).map((t) => t.id) : [id];
+      let bad = 0;
+      for (const w of worlds) {
+        try {
+          const r = await vary(w, { n: num(opts.n, 16), force: !!opts.force, seed: typeof opts.seed === "string" ? opts.seed : undefined, log: (l) => console.error(l) });
+          console.log(`${w}: 새 변주 ${r.made.length}개 · 있던 것 ${r.kept}개 · 탈락 ${r.rejected.length}개`);
+          if (r.kept + r.made.length + 1 < num(opts.n, 16)) bad++;
+        } catch (e) {
+          console.error(`kf theme vary ${w}: ${(e as Error).message}`);
+          bad++;
+        }
+      }
+      const code = await variantSheets(id, !!opts.share);
+      return bad ? 1 : code;
+    }
     if (!id) {
       console.error(`kf theme ${sub}: 테마 id 가 필요하다. kf theme --help`);
       return 2;
@@ -83,3 +134,170 @@ kf theme approve <id>               사람이 견본을 보고 OK 한 뒤에만
 };
 
 export default cmd;
+
+const ASPECTS: Aspect[] = ["9:16", "16:9", "1:1"];
+
+// 다른 도구(쇼츠 스킬 따위)가 kf make 와 같은 후보를 받아 가는 자리 — 고르기를 옮겨 적지 않게
+function suggest(opts: Record<string, string | boolean | undefined>): number {
+  const str = (k: string) => (typeof opts[k] === "string" ? (opts[k] as string) : "");
+  const purpose = (str("purpose") || "shorts") as Purpose;
+  const aspect = str("aspect") as Aspect;
+  if (!PURPOSES.includes(purpose)) {
+    console.error(`kf theme suggest: --purpose 는 ${PURPOSES.join("·")} 중 하나`);
+    return 2;
+  }
+  if (aspect && !ASPECTS.includes(aspect)) {
+    console.error(`kf theme suggest: --aspect 는 ${ASPECTS.join("·")} 중 하나`);
+    return 2;
+  }
+  const use = str("use").split(/[,·]/).map((w) => w.trim()).filter(Boolean);
+  const picks = suggestThemes(str("request"), purpose, aspect || undefined, num(opts.n, 4), { mood: str("mood") }, use);
+  const candidates = picks.map(({ id, why }) => {
+    const t = loadTheme(id);
+    return { id, world: t.world, variant: t.variant?.id ?? null, name: t.name, dims: t.tags?.dims ?? themeDims(t), why, cell: existsSync(cellPath(id)) ? cellPath(id) : null, sample: themeSample(t) };
+  });
+  if (opts.json) {
+    console.log(JSON.stringify({ request: str("request"), purpose, aspect: aspect || null, mood: str("mood"), use, candidates }, null, 1));
+    return 0;
+  }
+  if (!candidates.length) console.log("(맞는 approved 테마 없음)");
+  for (const [i, c] of candidates.entries()) console.log(`${i + 1}. ${c.name} · ${c.dims} (${c.id}) — ${c.why}`);
+  return 0;
+}
+
+// 견본 시트 — 테마끼리 견주려면 내용이 같아야 한다. 감독 모드가 실제로 짓는 장면(쇼츠 첫 장면 hook-number)을 테마만 바꿔,
+// 검사를 거쳐(떨어진 패턴은 감독이 다음 후보로 다시 짓는다) 사람이 실제로 받을 화면을 장면 끝 프레임에서 찍는다 — 움직임이 다 앉은 자리
+
+async function sheet(out: string): Promise<number> {
+  const themes = listThemes({ status: "approved" });
+  if (!themes.length) {
+    console.error("kf theme sheet: approved 테마가 없다");
+    return 1;
+  }
+  mkdirSync(dirname(out), { recursive: true });
+  const tmp = mkdtempSync(join(tmpdir(), "kf-theme-sheet-"));
+  const cells: { t: Theme; png: string; failed: boolean }[] = [];
+  let frame = { width: 1080, height: 1920, safe: { top: 0, bottom: 0, left: 0, right: 0 }, at: 0 };
+  try {
+    for (const t of themes) {
+      const dir = join(tmp, t.id);
+      const png = join(dirname(out), `${t.id}.png`);
+      const kf = (...a: string[]) => spawnSync(process.execPath, [kfBin, ...a], { encoding: "utf8" });
+      let r = kf("new", dir, "--template", "shorts", "--theme", t.id, "--title", SAMPLE.title, "--series", "none");
+      if (r.status === 0) {
+        writeFileSync(join(dir, "content.json"), `${JSON.stringify(SAMPLE, null, 2)}\n`);
+        r = kf("direct", dir, "--no-narrate", "--no-lock");
+      }
+      // 1 은 다시 지어도 검사 오류가 남았다는 뜻 — 찍되 칸에 표시한다
+      const failed = r.status === 1;
+      if (r.status === 0 || failed) {
+        const p = JSON.parse(readFileSync(join(dir, "kf.json"), "utf8"));
+        const scene = p.scenes.find((x: { id: string }) => x.id === SAMPLE.scenes[0].id);
+        frame = { width: p.width, height: p.height, safe: p.safeArea, at: +(scene.from + scene.dur - 1 / p.fps).toFixed(4) };
+        r = kf("still", dir, "--t", String(frame.at), "--out", png);
+      }
+      if (r.status !== 0) {
+        console.error(`테마 ${t.id}: 못 찍음 — ${`${r.stderr ?? ""}${r.stdout ?? ""}`.trim().split("\n").slice(-3).join(" / ")}`);
+        continue;
+      }
+      console.error(`테마 ${t.id}: ${png}${failed ? " — 검사 오류가 남았다(out/check.json)" : ""}`);
+      cells.push({ t, png, failed });
+    }
+    if (!cells.length) return 1;
+    const w = 360;
+    const h = Math.round((w * frame.height) / frame.width);
+    const k = w / frame.width;
+    const html = `<!doctype html><meta charset="utf-8"><style>
+      body { margin: 0; padding: 24px; background: #111; font: 16px/1.35 -apple-system, "Apple SD Gothic Neo", sans-serif; color: #ddd; }
+      h1 { margin: 0 0 16px; font-size: 18px; font-weight: 600; color: #fff; }
+      main { display: grid; grid-template-columns: repeat(${cells.length}, ${w}px); gap: 16px; }
+      figure { margin: 0; position: relative; }
+      .safe { position: absolute; left: 0; width: ${w}px; border-top: 2px dashed #ff4d4d; }
+      img { display: block; width: ${w}px; height: ${h}px; outline: 1px solid #333; }
+      figcaption { padding: 8px 2px 0; }
+      b { color: #fff; }
+      .d { display: inline-block; margin-left: 6px; padding: 0 6px; border: 1px solid #666; border-radius: 4px; font-size: 13px; }
+      small { display: block; color: #999; font-size: 13px; }
+      .bad { color: #ff6b6b; }
+    </style><h1>같은 문장 한 장면 — 「${SAMPLE.scenes[0].value}${SAMPLE.scenes[0].unit} ${SAMPLE.scenes[0].label}」 · 쇼츠 9:16 · 장면 끝 프레임(${frame.at}초) · 빨간 점선 밖은 플랫폼 UI 자리라 비운다</h1><main>${cells
+      .map(
+        ({ t, png, failed }) =>
+          `<figure><img src="data:image/png;base64,${readFileSync(png).toString("base64")}"><div class="safe" style="top:${Math.round(frame.safe.top * k)}px"></div><div class="safe" style="top:${Math.round((frame.height - frame.safe.bottom) * k)}px"></div><figcaption><b>${t.name}</b><span class="d">${themeDims(t)}</span><small>${t.id}${failed ? ' · <span class="bad">검사 오류 남음</span>' : ""}</small></figcaption></figure>`,
+      )
+      .join("")}</main>`;
+    const browser = await launch();
+    try {
+      const page = await browser.newPage({ viewport: { width: 48 + cells.length * w + (cells.length - 1) * 16, height: 400 } });
+      await page.setContent(html, { waitUntil: "load" });
+      writeFileSync(out, await page.screenshot({ fullPage: true, type: "png" }));
+    } finally {
+      await browser.close();
+    }
+    console.log(out);
+    return cells.length === themes.length && !cells.some((c) => c.failed) ? 0 : 1;
+  } finally {
+    rmSync(tmp, { recursive: true, force: true });
+  }
+}
+
+// 변주 격자 — 세계마다 기본+변주 한 장, all 이면 전체 한 장과 목록. 칸은 캐시(없거나 낡은 것만 찍는다)
+async function variantSheets(which: string, share: boolean): Promise<number> {
+  const worlds = which === "all" ? listThemes({ status: "approved" }).filter((t) => listVariants(t.id).length) : [loadTheme(which)];
+  if (!worlds.length) {
+    console.error("kf theme sheet --variants: 변주를 뽑은 세계가 없다 — kf theme vary <세계>");
+    return 1;
+  }
+  const tmp = mkdtempSync(join(tmpdir(), "kf-variant-sheet-"));
+  const out: string[] = [];
+  const every: { t: Theme; png: string }[] = [];
+  try {
+    for (const w of worlds) {
+      const ids = [w.id, ...listVariants(w.id).map((v) => `${w.id}/${v.id}`)];
+      const cells = ensureCells(ids, join(tmp, w.id), (l) => console.error(l));
+      const themes = ids.filter((i) => cells.has(i)).map((i) => loadTheme(i));
+      const frame = cellFrame(w.id) ?? { width: 1080, height: 1920, safe: { top: 230, bottom: 460, left: 40, right: 40 } };
+      const file = join(cellsDir, w.id, "sheet.png");
+      await gridSheet(
+        themes.map((t) => cellOf(t, cells.get(t.id)!)),
+        file,
+        { heading: `${w.name}(${w.id}) — 기본 + 변주 ${themes.length - 1} · 같은 문장 한 장면(쇼츠 9:16) 끝 프레임 · ${w.status === "approved" ? "세계가 approved 라 검사를 넘은 변주는 바로 쓴다" : "세계가 review 라 변주도 review"} · 빨간 점선 밖은 플랫폼 UI 자리`, cols: 8, w: 240, frame },
+      );
+      console.log(file);
+      out.push(file);
+      every.push(...themes.map((t) => ({ t, png: cells.get(t.id)! })));
+    }
+    let list: string | null = null;
+    if (which === "all") {
+      const frame = cellFrame(worlds[0].id) ?? { width: 1080, height: 1920, safe: { top: 230, bottom: 460, left: 40, right: 40 } };
+      const all = join(cellsDir, "all.png");
+      await gridSheet(
+        every.map(({ t, png }): GridCell => ({ png, title: t.variant ? t.variant.name : `${t.world} 기본`, sub: t.world, swatches: [t.style.colors.bg, t.style.colors.ink, t.style.colors.accent] })),
+        all,
+        { heading: `approved 세계 ${worlds.length} × 변주 — 모두 ${every.length}판 · 같은 문장 한 장면`, cols: 16, w: 150, frame },
+      );
+      console.log(all);
+      out.push(all);
+      list = join(cellsDir, "변주목록.md");
+      writeFileSync(
+        list,
+        [`# kasaframe 테마 변주 — ${every.length}판`, "", "부르는 이름은 `<세계>/<변주>` — `kf make --theme`·`kf new --theme`·시리즈 `theme`·kf.json `theme` 어디서나.", "", "| 이름 | 밝기 | 설명 | 분위기 |", "|---|---|---|---|",
+          ...every.map(({ t }) => `| \`${t.id}\` | ${t.style.scheme} | ${t.variant?.desc ?? `세계 그대로 — ${t.metaphor}`} | ${(t.tags?.mood ?? []).join("·")} |`)].join("\n") + "\n",
+      );
+      console.log(list);
+    }
+    if (share) {
+      const r = spawnSync("kasaterm-cli", ["share", "new", "kasaframe-테마-변주"], { encoding: "utf8" });
+      let dir = r.status === 0 ? (r.stdout.trim().split("\n").pop() ?? "") : "";
+      if (!dir || !existsSync(dir)) {
+        dir = join(homedir(), "Desktop", "kasaframe-테마-변주");
+        mkdirSync(dir, { recursive: true });
+      }
+      for (const f of out) copyFileSync(f, join(dir, f.endsWith("all.png") ? "전체.png" : `${f.split("/").at(-2)}.png`));
+      if (list) copyFileSync(list, join(dir, "변주목록.md"));
+      console.log(`공유 폴더 ${dir}`);
+    }
+    return 0;
+  } finally {
+    rmSync(tmp, { recursive: true, force: true });
+  }
+}

package/packages/cli/src/deps.ts

@@ -43,8 +43,8 @@ function installHint(pkg: { brew: string; apt: string; url: string }): string {
 
 function node(): Check {
   const [major, minor] = process.versions.node.split(".").map(Number);
-  const ok = major > 22 || (major === 22 && minor >= 18);
-  return { name: "Node 22.18 이상", ok, required: true, detail: process.version, fix: ok ? undefined : "https://nodejs.org 에서 22 LTS 이상" };
+  const ok = major > 22 || (major === 22 && minor >= 15);
+  return { name: "Node 22.15 이상", ok, required: true, detail: process.version, fix: ok ? undefined : "https://nodejs.org 에서 22 LTS 이상" };
 }
 
 function ffmpeg(): Check {
@@ -56,7 +56,7 @@ function ffmpeg(): Check {
     ok,
     required: true,
     detail: ok ? (/version (\S+)/.exec(r.stdout)?.[1] ?? "있음") : "없음 — MP4 로 굽기·검사에 쓴다",
-    fix: ok ? undefined : installHint({ brew: "ffmpeg", apt: "ffmpeg", url: "https://ffmpeg.org/download.html" }),
+    fix: ok ? undefined : `${installHint({ brew: "ffmpeg", apt: "ffmpeg", url: "https://ffmpeg.org/download.html" })} — PATH 밖 정적 빌드면 KF_FFMPEG=<ffmpeg 경로> KF_FFPROBE=<ffprobe 경로>`,
   };
 }
 
@@ -72,7 +72,7 @@ async function chrome(): Promise<Check> {
   }
 }
 
-function librosa(): Check {
+export function librosa(): Check {
   const py = python();
   const r = run(py, ["-c", "import librosa; print(librosa.__version__)"]);
   const ok = r.status === 0;
@@ -110,8 +110,8 @@ export async function checks(): Promise<Check[]> {
 }
 
 // 한글은 터미널에서 두 칸을 먹는다 — padEnd 로는 열이 어긋난다
-const cols = (s: string) => [...s].reduce((n, ch) => n + (/[\u1100-\u11ff\u3000-\u9fff\uac00-\ud7af]/.test(ch) ? 2 : 1), 0);
-const pad = (s: string, n: number) => s + " ".repeat(Math.max(0, n - cols(s)));
+export const cols = (s: string) => [...s].reduce((n, ch) => n + (/[\u1100-\u11ff\u3000-\u9fff\uac00-\ud7af]/.test(ch) ? 2 : 1), 0);
+export const pad = (s: string, n: number) => s + " ".repeat(Math.max(0, n - cols(s)));
 
 export function report(list: Check[]): void {
   const w = Math.max(...list.map((c) => cols(c.name))) + 2;

package/packages/cli/src/kf.ts

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import { readdirSync } from "node:fs";
 import { fileURLToPath } from "node:url";
+import { fontsMissing } from "@kasaframe/jizura/install";
 import type { Command } from "./command.ts";
 
 const commandsDir = fileURLToPath(new URL("./commands/", import.meta.url));
@@ -44,10 +45,20 @@ async function main(argv: string[]): Promise<number> {
   return (await cmd.run(rest)) ?? 0;
 }
 
+// 가사 층 글꼴을 처음 쓰다 못 받았으면(서버가 받는다 — jizura/vite.ts) 다른 글꼴로 구운 결과 대신 고를 길을 찍는다.
+// 명령이 실패했으면 종료 3, 그 글꼴을 쓰는 프레임 없이 끝났으면 그대로
+async function finish(code: number): Promise<number> {
+  const miss = fontsMissing();
+  if (!miss.length) return code;
+  const [{ fontsQuestion }, { questionsText }] = await Promise.all([import("./commands/lyrics.ts"), import("@kasaframe/gen")]);
+  console.error(`\n${code ? "" : "이번 구간은 그 글꼴 없이 끝났다 — 그 플랜이 나오는 구간을 구우려면 먼저 고른다\n"}${questionsText([fontsQuestion(miss)])}`);
+  return code ? 3 : code;
+}
+
 main(process.argv.slice(2)).then(
-  (code) => process.exit(code),
-  (err) => {
+  async (code) => process.exit(await finish(code)),
+  async (err) => {
     console.error(err instanceof Error ? (err.stack ?? err.message) : err);
-    process.exit(1);
+    process.exit(await finish(1));
   },
 );

package/packages/cli/src/lock.ts

@@ -31,18 +31,20 @@ export async function acquireRenderLock(dir: string, waitSec: number): Promise<(
       mkdirSync(LOCK);
       writeFileSync(join(LOCK, "owner.json"), JSON.stringify({ pid: process.pid, dir, started: new Date().toISOString() }));
       let held = true;
+      const onSig = () => {
+        release();
+        process.exit(130);
+      };
+      // 한 프로세스가 잠금을 여러 번 쥐었다 놓는다(kf theme vary 는 변주마다) — 놓을 때 건 귀를 떼야 쌓이지 않는다
       const release = () => {
         if (!held) return;
         held = false;
+        process.off("exit", release);
+        for (const sig of ["SIGINT", "SIGTERM"] as const) process.off(sig, onSig);
         if (owner()?.pid === process.pid) rmSync(LOCK, { recursive: true, force: true });
       };
       process.once("exit", release);
-      for (const sig of ["SIGINT", "SIGTERM"] as const) {
-        process.once(sig, () => {
-          release();
-          process.exit(130);
-        });
-      }
+      for (const sig of ["SIGINT", "SIGTERM"] as const) process.once(sig, onSig);
       return release;
     } catch (err) {
       if ((err as NodeJS.ErrnoException).code !== "EEXIST") throw err;