kasaframe 0.0.0-stage → 0.1.3

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

@@ -0,0 +1,172 @@
+import { spawnSync } from "node:child_process";
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { listThemes, sheetDir, type Theme, themeDims, themesDir } from "@kasaframe/themes";
+import { briefs, review, scaffold, sessionPrompt, setStatus, staticCheck } from "@kasaframe/themes/factory";
+import { launch } from "../browser.ts";
+import { type Command, num, parseFlags } from "../command.ts";
+
+const kfBin = new URL("../kf.ts", import.meta.url).pathname;
+
+const cmd: Command = {
+  summary: "테마 공장 — 참고 자료로 테마 팩 뼈대·지시서, 계약 검사, 견본 review, 사람 OK 뒤 approve",
+  usage: `kf theme list
+kf theme new <id> --ref <그림·영상·폴더·URL> [--ref …] [--name 이름] [--like <기존 테마>] [--3d] [--brief ${briefs().join("|")}] [--force]
+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 sheet [--out 파일.png]     approved 테마마다 같은 문장 한 장면(쇼츠 9:16)을 감독 모드로 짓고 검사를 거쳐, 장면 끝 프레임을
+                                    격자 한 장으로 — 이름·2D/3D 딱지, 안전 영역 점선. 기본 themes/_sheet/sheet.png, 칸은 그 옆 <id>.png
+                                    (kf make 의 테마 질문 보기가 이 칸을 견본으로 짚는다). 검사 오류가 남은 칸은 표시하고 종료 1
+
+  new 는 themes/<id>/ 에 계약 파일 뼈대·refs/·브리프대로 자른 곡과 박·장면 넷 뼈대·THEME-MAKE.md(지시서)를 짓고,
+  그 지시서를 받을 세션을 여는 명령을 알려 준다. 테마는 그 세션이 만든다.`,
+  async run(argv) {
+    const [sub, ...rest] = argv;
+    const { args, opts } = parseFlags(rest);
+    const id = args[0];
+    if (sub === "sheet") return sheet(resolve(typeof opts.out === "string" ? opts.out : join(sheetDir, "sheet.png")));
+    if (sub === "list" || !sub) {
+      const all = listThemes();
+      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}`);
+      return 0;
+    }
+    if (!id) {
+      console.error(`kf theme ${sub}: 테마 id 가 필요하다. kf theme --help`);
+      return 2;
+    }
+    if (sub === "new") {
+      // --ref 는 여러 번 — parseFlags 는 마지막 하나만 남기니 따로 모은다
+      const refs = rest.flatMap((a, i) => (a === "--ref" && rest[i + 1] ? [rest[i + 1]] : a.startsWith("--ref=") ? [a.slice(6)] : []));
+      try {
+        const r = scaffold(id, {
+          refs,
+          name: typeof opts.name === "string" ? opts.name : undefined,
+          like: typeof opts.like === "string" ? opts.like : undefined,
+          brief: typeof opts.brief === "string" ? opts.brief : undefined,
+          kind: opts["3d"] ? "3d" : "flat",
+          force: !!opts.force,
+        });
+        console.log(`${r.dir}/ — 참고 자료 ${r.refs.length}개${r.urls.length ? ` · 주소 ${r.urls.length}개` : ""}`);
+        console.log(`지시서: ${r.make}`);
+        console.log(`\n세션 열기(레포 뿌리에서):\n  claude --model opus "${sessionPrompt(id)}"`);
+        return 0;
+      } catch (e) {
+        console.error(`kf theme new: ${(e as Error).message}`);
+        return 2;
+      }
+    }
+    if (sub === "check") {
+      const bad = await staticCheck(id);
+      for (const b of bad) console.log(`[오류] ${b}`);
+      if (!bad.length) console.log("계약·빈칸: 통과");
+      let page = 0;
+      if (!opts["no-page"]) page = spawnSync(process.execPath, [kfBin, "check", join(themesDir, id, "sample"), "--tabs", String(num(opts.tabs, 2))], { stdio: "inherit" }).status ?? 1;
+      return bad.length || page ? 1 : 0;
+    }
+    if (sub === "review") {
+      const bad = await staticCheck(id);
+      if (bad.length) {
+        for (const b of bad) console.log(`[오류] ${b}`);
+        console.error("kf theme review: 계약·빈칸 오류부터 — kf theme check");
+        return 1;
+      }
+      const r = review(id, { tabs: num(opts.tabs, 2), brief: typeof opts.brief === "string" ? opts.brief : undefined });
+      for (const n of r.notes) console.log(n);
+      if (!r.ok) return 1;
+      console.log(`status review · 공유 폴더 ${r.share}`);
+      return 0;
+    }
+    if (sub === "approve") {
+      const m = setStatus(id, "approved");
+      console.log(`${id} approved ${m.approvedAt} — 사람이 견본을 보고 OK 한 테마만`);
+      return 0;
+    }
+    console.error(`kf theme: 모르는 하위 명령 "${sub}". kf theme --help`);
+    return 2;
+  },
+};
+
+export default cmd;
+
+// 견본 시트 — 테마끼리 견주려면 내용이 같아야 한다. 감독 모드가 실제로 짓는 장면(쇼츠 첫 장면 hook-number)을 테마만 바꿔,
+// 검사를 거쳐(떨어진 패턴은 감독이 다음 후보로 다시 짓는다) 사람이 실제로 받을 화면을 장면 끝 프레임에서 찍는다 — 움직임이 다 앉은 자리
+const SAMPLE = {
+  title: "kasaframe",
+  request: "테마 견본 — 같은 문장을 테마마다",
+  scenes: [{ id: "hook", type: "hook-number", value: 57, unit: "×", label: "KV 캐시가 이만큼 작아진다", source: "DeepSeek-V2 기술 보고서", dur: 4 }],
+};
+
+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 });
+  }
+}

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

@@ -0,0 +1,40 @@
+import type { Command } from "../command.ts";
+import { parseFlags } from "../command.ts";
+import { CATALOG, type TransitionEntry } from "@kasaframe/motion/transitions2d";
+
+const USE: Record<TransitionEntry["use"], string> = { transition3d: "이름으로", react: "React 부품", vendor: "원본만" };
+
+const cmd: Command = {
+  summary: "전환 목록 — 이름·출처·라이선스·seek/step",
+  usage: `kf transitions [찾을 말] [--source 출처] [--clock seek|step] [--use transition3d|react|vendor] [--json]
+  이름으로(transition3d) 인 것은 장면에서 transition3d(root, ctx, { kind: "<이름>" }) 로 부른다 — 예 gl:crosswarp · smooth:sdf-circle · dive
+  React 부품은 @kasaframe/motion/transitions2d/react, 원본만은 geono-hub vendor/transitions/ 에 있다
+  step 은 자기 시계(rAF·타이머)라 kf.json 의 mode 를 "step" 으로`,
+  async run(argv) {
+    const { args, opts } = parseFlags(argv);
+    const has = (v: string, q: unknown) => typeof q !== "string" || v.toLowerCase().includes(q.toLowerCase());
+    const list = CATALOG.filter(
+      (e) =>
+        has(e.source, opts.source) &&
+        (typeof opts.clock !== "string" || e.clock === opts.clock) &&
+        (typeof opts.use !== "string" || e.use === opts.use) &&
+        args.every((q) => has(`${e.name} ${e.note ?? ""} ${e.author ?? ""}`, q)),
+    );
+    if (opts.json) {
+      console.log(JSON.stringify(list, null, 2));
+      return 0;
+    }
+    const count = (k: (e: TransitionEntry) => string) => [...list.reduce((m, e) => m.set(k(e), (m.get(k(e)) ?? 0) + 1), new Map<string, number>())].map(([k, n]) => `${k} ${n}`).join(" · ");
+    console.log(`${list.length}개 — ${count((e) => e.source)}`);
+    console.log(`시계 ${count((e) => e.clock)} · ${count((e) => USE[e.use])}\n`);
+    const w = Math.max(...list.map((e) => e.name.length), 4) + 2;
+    const sw = Math.max(...list.map((e) => e.source.length), 4) + 2;
+    const lw = Math.max(...list.map((e) => e.license.length), 4) + 2;
+    for (const e of list) {
+      const extra = [e.component && `<${e.component}>`, e.author, e.note].filter(Boolean).join(" — ");
+      console.log(`${e.name.padEnd(w)}${e.source.padEnd(sw)}${e.license.padEnd(lw)}${e.clock.padEnd(6)}${USE[e.use].padEnd(9)}${extra}`);
+    }
+    return 0;
+  },
+};
+export default cmd;

package/packages/cli/src/deps.ts

@@ -0,0 +1,122 @@
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { createRequire } from "node:module";
+import { homedir, platform } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { hasKey, whereToPut } from "@kasaframe/gen";
+import { jizuraCheck } from "@kasaframe/jizura/install";
+import { launch } from "./browser.ts";
+import { lyricsCheck } from "./commands/lyrics.ts";
+
+// kf doctor·kf setup 이 같이 보는 바깥 도구들 — npm 이 못 까는 것(ffmpeg·파이썬 꾸러미·크롬 본체)만.
+
+export const requirements = fileURLToPath(new URL("../../../tools/beats/requirements.txt", import.meta.url));
+// 요즘 파이썬(Homebrew·데비안)은 시스템에 pip 설치를 막는다(PEP 668) — kf setup 은 쓰임마다 venv 를 따로 둔다
+export const pyVenv = (name: string): string => join(homedir(), ".cache", "kasaframe", "py", name);
+export const venvPython = (dir: string): string => join(dir, platform() === "win32" ? "Scripts/python.exe" : "bin/python");
+export const beatsVenv = pyVenv("beats");
+
+export function python(): string {
+  return process.env.KF_PYTHON ?? (existsSync(venvPython(beatsVenv)) ? venvPython(beatsVenv) : "python3");
+}
+
+// npx playwright 는 다른 판의 playwright 를 집을 수 있다 — 크롬 판이 이 패키지가 쓰는 playwright 와 맞아야 뜬다
+export const playwrightCli = (): string => join(dirname(createRequire(import.meta.url).resolve("playwright/package.json")), "cli.js");
+
+export interface Check {
+  name: string;
+  ok: boolean;
+  /** 없으면 렌더가 안 된다 */
+  required: boolean;
+  detail: string;
+  fix?: string;
+}
+
+const run = (cmd: string, args: string[]) => spawnSync(cmd, args, { encoding: "utf8" });
+
+function installHint(pkg: { brew: string; apt: string; url: string }): string {
+  if (platform() === "darwin") return `brew install ${pkg.brew}`;
+  if (platform() === "linux") return `sudo apt-get install -y ${pkg.apt}  (데비안·우분투 — 다른 배포판은 그 패키지 관리자로)`;
+  return pkg.url;
+}
+
+function node(): Check {
+  const [major, minor] = process.versions.node.split(".").map(Number);
+  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 {
+  const r = run("ffmpeg", ["-hide_banner", "-version"]);
+  const p = run("ffprobe", ["-hide_banner", "-version"]);
+  const ok = r.status === 0 && p.status === 0;
+  return {
+    name: "ffmpeg·ffprobe",
+    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" })} — PATH 밖 정적 빌드면 KF_FFMPEG=<ffmpeg 경로> KF_FFPROBE=<ffprobe 경로>`,
+  };
+}
+
+async function chrome(): Promise<Check> {
+  try {
+    const b = await launch();
+    const v = b.version();
+    await b.close();
+    return { name: "크롬(Playwright)", ok: true, required: true, detail: v };
+  } catch (err) {
+    const first = String(err instanceof Error ? err.message : err).split("\n")[0];
+    return { name: "크롬(Playwright)", ok: false, required: true, detail: `못 띄웠다 — ${first.slice(0, 120)}`, fix: `kf setup chrome  (같은 일: node ${playwrightCli()} install chromium${platform() === "linux" ? " · 리눅스는 sudo 로 install-deps chromium 도" : ""})` };
+  }
+}
+
+export function librosa(): Check {
+  const py = python();
+  const r = run(py, ["-c", "import librosa; print(librosa.__version__)"]);
+  const ok = r.status === 0;
+  return {
+    name: "python3 + librosa",
+    ok,
+    required: false,
+    detail: ok ? `${py} · librosa ${r.stdout.trim()}` : `${py} 에 없다 — 곡에 박자를 맞출 때(kf beats·--music)만 쓴다`,
+    fix: ok ? undefined : `kf setup beats  (같은 일: python3 -m venv ${beatsVenv} && ${venvPython(beatsVenv)} -m pip install -r ${requirements})`,
+  };
+}
+
+function ogKey(): Check {
+  const ok = hasKey("opengateway");
+  return {
+    name: "OG 키",
+    ok,
+    required: false,
+    detail: ok ? "있음 — 그림 생성(kf gen)·kf make OG 모드" : "없음 — 그림 생성(kf gen)과 kf make OG 모드만 못 쓴다. 장면·렌더·검사는 키 없이 돈다",
+    fix: ok ? undefined : whereToPut("opengateway"),
+  };
+}
+
+// 글꼴은 CDN(jsdelivr)에서 받지만, 망이 막힌 리눅스 상자에서는 한글이 두부로 나온다
+function koreanFont(): Check | null {
+  if (platform() !== "linux") return null;
+  const r = run("fc-list", [":lang=ko", "family"]);
+  const ok = r.status === 0 && r.stdout.trim().length > 0;
+  return { name: "한글 글꼴", ok, required: false, detail: ok ? r.stdout.trim().split("\n")[0] : "없음 — 글꼴 CDN 이 막히면 한글이 두부로 나온다", fix: ok ? undefined : "sudo apt-get install -y fonts-noto-cjk" };
+}
+
+// 점검을 더할 땐 여기 한 줄 — kf doctor 와 kf setup 끝 표가 같이 쓴다
+export async function checks(): Promise<Check[]> {
+  return [node(), ffmpeg(), await chrome(), librosa(), jizuraCheck(), lyricsCheck(), ogKey(), koreanFont()].filter((c): c is Check => c !== null);
+}
+
+// 한글은 터미널에서 두 칸을 먹는다 — padEnd 로는 열이 어긋난다
+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;
+  for (const c of list) {
+    console.log(`  ${pad(c.ok ? "ok" : c.required ? "없음" : "선택", 4)}  ${pad(c.name, w)}${c.detail}`);
+    if (c.fix) console.log(`  ${pad("", 4 + 2 + w)}→ ${c.fix}`);
+  }
+}

package/packages/cli/src/ffmpeg.ts

@@ -0,0 +1,81 @@
+import { spawn, type ChildProcess } from "node:child_process";
+import { once } from "node:events";
+
+export type VideoFormat = "h264" | "prores";
+
+export interface Encoder {
+  /** PNG, raw 로 만들었으면 RGBA 날것 */
+  write(frame: Buffer): Promise<void>;
+  end(): Promise<void>;
+}
+
+function run(args: string[], label: string): { proc: ChildProcess; done: Promise<void> } {
+  const proc = spawn("ffmpeg", ["-hide_banner", "-loglevel", "error", "-y", ...args], {
+    stdio: ["pipe", "ignore", "pipe"],
+  });
+  let err = "";
+  proc.stderr!.on("data", (d) => (err += d));
+  const done = new Promise<void>((resolve, reject) => {
+    proc.on("error", (e) => reject(new Error(`${label}: ffmpeg 를 못 띄웠다 (${e.message})`)));
+    proc.on("close", (code) => (code === 0 ? resolve() : reject(new Error(`${label}: ffmpeg 종료 ${code}\n${err.trim()}`))));
+  });
+  return { proc, done };
+}
+
+// RGB→YUV 를 BT.709 로 바꾸고 그렇다고 적는다. 안 적으면 ffmpeg 는 BT.601 로 바꾸는데 브라우저·유튜브는 HD 를 709 로 풀어
+// 색이 어긋난다(#20C040 이 (20,168,61) 로 — 초록이 눌린다)
+const BT709 = ["-vf", "scale=out_color_matrix=bt709:out_range=tv,setparams=color_primaries=bt709:color_trc=bt709:colorspace=bt709", "-colorspace", "bt709", "-color_primaries", "bt709", "-color_trc", "bt709"];
+
+const CODEC: Record<VideoFormat, string[]> = {
+  h264: ["-c:v", "libx264", "-preset", "medium", "-crf", "16", "-pix_fmt", "yuv420p", ...BT709, "-movflags", "+faststart"],
+  prores: ["-c:v", "prores_ks", "-profile:v", "3", "-pix_fmt", "yuv422p10le", ...BT709, "-vendor", "apl0"],
+};
+
+// PNG(또는 raw 를 주면 RGBA 날것 — 모션 블러가 평균한 프레임)를 stdin 으로 흘려 구간 파일 하나를 만든다. 쓰기가 밀리면 기다려 메모리가 차지 않게 한다.
+export function encoder(out: string, fps: number, format: VideoFormat, crf?: number, raw?: { width: number; height: number }): Encoder {
+  const codec = [...CODEC[format]];
+  if (crf !== undefined && format === "h264") codec[codec.indexOf("-crf") + 1] = String(crf);
+  const input = raw
+    ? ["-f", "rawvideo", "-pix_fmt", "rgba", "-s", `${raw.width}x${raw.height}`, "-framerate", String(fps), "-i", "-"]
+    : ["-f", "image2pipe", "-framerate", String(fps), "-c:v", "png", "-i", "-"];
+  const { proc, done } = run([...input, ...codec, "-r", String(fps), out], out);
+  const stdin = proc.stdin!;
+  let failed: Error | null = null;
+  done.catch((e) => (failed = e));
+  return {
+    async write(frame) {
+      if (failed) throw failed;
+      if (!stdin.write(frame)) await Promise.race([once(stdin, "drain"), done]);
+    },
+    async end() {
+      stdin.end();
+      await done;
+    },
+  };
+}
+
+// 구간들을 다시 인코딩하지 않고 잇고, 곡이 있으면 그 구간만큼 잘라 얹는다.
+export async function concat(o: {
+  list: string;
+  out: string;
+  format: VideoFormat;
+  music?: string;
+  from: number;
+  dur: number;
+}): Promise<void> {
+  const args = ["-f", "concat", "-safe", "0", "-i", o.list];
+  if (o.music) args.push("-ss", o.from.toFixed(6), "-i", o.music);
+  args.push("-map", "0:v:0");
+  if (o.music) {
+    args.push("-map", "1:a:0", ...(o.format === "prores" ? ["-c:a", "pcm_s16le"] : ["-c:a", "aac", "-b:a", "256k"]));
+    args.push("-af", `apad`, "-t", o.dur.toFixed(6));
+  }
+  args.push("-c:v", "copy");
+  // concat 이 구간 파일의 primaries·trc 태그를 떨군다 — 다시 인코딩 없이 비트스트림에 709 를 다시 적는다
+  args.push("-bsf:v", o.format === "h264" ? "h264_metadata=colour_primaries=1:transfer_characteristics=1:matrix_coefficients=1" : "prores_metadata=color_primaries=bt709:color_trc=bt709:colorspace=bt709");
+  args.push("-colorspace", "bt709", "-color_primaries", "bt709", "-color_trc", "bt709");
+  if (o.format === "h264") args.push("-movflags", "+faststart");
+  args.push(o.out);
+  const { done } = run(args, o.out);
+  await done;
+}

package/packages/cli/src/index.ts

@@ -0,0 +1,8 @@
+export type { Command, Flags } from "./command.ts";
+export { parseFlags, num } from "./command.ts";
+export { openProject, repoRoot } from "./serve.ts";
+export type { OpenProject, OpenProjectOptions } from "./serve.ts";
+export { openPage, openSession, launch, Tab } from "./browser.ts";
+export type { OpenPage, PageInfo, PageMeta, Session, SessionOptions } from "./browser.ts";
+export { blurOpts, captureBlurred, rgbaToPng, subTimes } from "./blur.ts";
+export type { BlurOpts } from "./blur.ts";

package/packages/cli/src/kf.ts

@@ -0,0 +1,64 @@
+#!/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));
+
+function available(): string[] {
+  return readdirSync(commandsDir)
+    .filter((f) => f.endsWith(".ts") && !f.endsWith(".test.ts"))
+    .map((f) => f.slice(0, -3))
+    .sort();
+}
+
+async function load(name: string): Promise<Command> {
+  const mod = await import(new URL(`./commands/${name}.ts`, import.meta.url).href);
+  return mod.default as Command;
+}
+
+async function help(): Promise<void> {
+  console.log("kf <명령> [인자]\n");
+  for (const name of available()) {
+    const cmd = await load(name).catch(() => null);
+    console.log(`  ${name.padEnd(10)} ${cmd?.summary ?? ""}`);
+  }
+  console.log("\nkf <명령> --help 로 인자를 본다.");
+}
+
+async function main(argv: string[]): Promise<number> {
+  const [name, ...rest] = argv;
+  if (!name || name === "help" || name === "--help" || name === "-h") {
+    await help();
+    return 0;
+  }
+  if (!available().includes(name)) {
+    console.error(`kf: 모르는 명령 "${name}". 있는 명령: ${available().join(" ")}`);
+    return 2;
+  }
+  const cmd = await load(name);
+  if (rest.includes("--help") || rest.includes("-h")) {
+    console.log(`kf ${name} — ${cmd.summary}\n\n${cmd.usage ?? ""}`.trimEnd());
+    return 0;
+  }
+  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(
+  async (code) => process.exit(await finish(code)),
+  async (err) => {
+    console.error(err instanceof Error ? (err.stack ?? err.message) : err);
+    process.exit(await finish(1));
+  },
+);

package/packages/cli/src/lock.ts

@@ -0,0 +1,72 @@
+import { mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { installed, repoRoot } from "./serve.ts";
+
+const LOCK = installed ? join(tmpdir(), "kasaframe-render-lock") : join(repoRoot, ".render-lock");
+
+function alive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function owner(): { pid: number; dir: string; started: string } | null {
+  try {
+    return JSON.parse(readFileSync(join(LOCK, "owner.json"), "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+// 최종 렌더는 레포 전체에서 하나씩 — mkdir 이 원자적이라 먼저 만든 쪽만 이긴다.
+export async function acquireRenderLock(dir: string, waitSec: number): Promise<() => void> {
+  const until = Date.now() + waitSec * 1000;
+  let told = false;
+  for (;;) {
+    try {
+      mkdirSync(LOCK);
+      writeFileSync(join(LOCK, "owner.json"), JSON.stringify({ pid: process.pid, dir, started: new Date().toISOString() }));
+      let held = true;
+      const release = () => {
+        if (!held) return;
+        held = false;
+        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);
+        });
+      }
+      return release;
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code !== "EEXIST") throw err;
+    }
+    const o = owner();
+    // 남이 mkdir 하고 owner.json 을 쓰기 전 찰나일 수 있으니, 주인 없는 잠금은 10초 지난 것만 치운다.
+    const age = (() => {
+      try {
+        return Date.now() - statSync(LOCK).mtimeMs;
+      } catch {
+        return 0;
+      }
+    })();
+    if ((o && !alive(o.pid)) || (!o && age > 10_000)) {
+      rmSync(LOCK, { recursive: true, force: true });
+      continue;
+    }
+    if (Date.now() > until) {
+      throw new Error(`렌더 잠금을 못 얻었다 — ${o ? `pid ${o.pid} 가 ${o.dir} 를 ${o.started} 부터 굽는 중` : LOCK}`);
+    }
+    if (!told) {
+      console.error(`렌더 잠금 기다리는 중${o ? ` (pid ${o.pid}: ${o.dir})` : ""} — 최대 ${waitSec}초`);
+      told = true;
+    }
+    await new Promise((r) => setTimeout(r, 2000));
+  }
+}