kasaframe 0.0.0-stage → 0.1.3

package/app/server/engine.ts

@@ -0,0 +1,533 @@
+import { type ChildProcess, spawn } from "node:child_process";
+import { EventEmitter } from "node:events";
+import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { basename, extname, join, relative, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+import { checkContent } from "@kasaframe/director";
+import { capabilities } from "@kasaframe/gen";
+import { listTemplates, makePlan, type Plan, type Purpose, planQuestions, suggestThemes } from "@kasaframe/plan";
+import { loadTheme, themeCards, type ThemeStatus } from "@kasaframe/themes";
+import { captionMode } from "@kasaframe/motion/captions";
+
+// 화면과 상관없는 엔진 — HTTP 서버든 Electron 이든 컨테이너든 이걸 감싸기만 한다. 일은 전부 kf 명령을 자식 프로세스로 돌린다.
+
+const repo = fileURLToPath(new URL("../../", import.meta.url));
+const kfBin = join(repo, "packages/cli/src/kf.ts");
+export const dataDir = resolve(process.env.KF_APP_DIR ?? join(repo, "out", "app"));
+export const templatePreview = (id: string) => join(repo, "templates", id, "preview.png");
+// 5159 는 작업실 화면의 HMR 자리
+const PREVIEW_PORTS = [5151, 5152, 5153, 5154, 5155, 5156, 5157, 5158];
+
+export type Phase = "plan" | "scaffold" | "gen" | "scenes" | "render" | "check" | "done" | "waiting" | "failed";
+
+// 장면마다 따로 흐르는 상태 — kf make·direct·render 가 찍는 「장면 <id>: <상태>」 줄에서 읽는다
+export type SceneState = "writing" | "written" | "assets" | "render" | "rendered" | "reused" | "check" | "done" | "failed";
+const SCENE_WORDS: Record<string, SceneState> = { "쓰는 중": "writing", 씀: "written", 재료: "assets", 렌더: "render", 구움: "rendered", 그대로: "reused", 검사: "check", 끝: "done", 실패: "failed" };
+const SCENE_LINE = /^장면 (\S+): (쓰는 중|씀|재료|렌더|구움|그대로|검사|끝|실패)(?:\s*(?:—\s*)?(.*))?$/;
+
+export interface JobInput {
+  request: string;
+  purpose?: Purpose | "auto";
+  music?: string;
+  assets?: string[]; // /api/upload 로 올린 파일 경로들 — 일 폴더 in/ 에 모아 kf make --assets 로 넘긴다
+  theme?: string; // 테마 id 나 "auto"
+  model?: string;
+  approve?: boolean;
+  title?: string;
+  captions?: "on" | "off"; // 화면 자막 — 안 주면 틀 기본
+  answers?: Record<string, string>; // 계획의 asks 에 고른 답 { 질문 id: 값 } — kf make --<id> <값> 로 넘겨 묻지 않고 간다
+}
+
+export interface Job {
+  id: string;
+  external?: boolean; // 말로 시작한 kf make 가 스스로 등록한 일 — 서버가 돌리지 않고 진행만 받는다
+  input: JobInput;
+  dir: string;
+  phase: Phase;
+  progress: number; // 렌더 진행 0..1
+  running: boolean;
+  createdAt: number;
+  previewUrl?: string;
+  log: string[];
+  error?: string;
+  checkPassed?: boolean;
+  scenes?: Record<string, { state: SceneState; note?: string; at: number }>;
+  // 사람이 고쳐 다시 굽는 장면 — 다 되면 화면이 그 장면 시각부터 튼다
+  focus?: string;
+}
+
+export interface JobView extends Omit<Job, "log"> {
+  plan?: Plan;
+  kf?: unknown;
+  // alt — 자막을 반대로 다시 구운 판(video-자막.mp4 · video-자막없음.mp4). captions — 들릴 말(captions.json)이 있다
+  files: { video?: string; cover?: string; check?: string; alt?: string; captions?: string; videoAt?: number };
+}
+
+export interface SceneDetail {
+  scene: Record<string, unknown> & { id: string; from: number; dur: number; role?: string; idea?: string };
+  direct: boolean;
+  model: string | null;
+  content: Record<string, unknown> | null;
+  pattern: string | null;
+  candidates: { id: string; score: number; why: string[] }[];
+  pinned: { pattern?: string; seed?: string } | null;
+  assets: { path: string; url: string; kind: "image" | "video" }[];
+}
+
+const PHASES: [RegExp, Phase][] = [
+  [/^용도 /, "scaffold"],
+  [/^생성 자산/, "gen"],
+  [/^계획 다듬/, "scaffold"],
+  [/^장면 \S+: 쓰는 중/, "scenes"],
+  [/^장면 \S+: 재료/, "gen"],
+  [/^장면 \S+: 렌더/, "render"],
+  [/^장면 \S+: 검사/, "check"],
+  [/^\s+\S+ \d+번째/, "scenes"],
+  [/^\s+\d+\/\d+ \(\d+%\)/, "render"],
+  [/^고치기 /, "scenes"],
+  [/^그림 검사/, "check"],
+];
+
+export class Engine extends EventEmitter {
+  jobs = new Map<string, Job>();
+  private procs = new Map<string, ChildProcess>();
+  private previews = new Map<string, { proc: ChildProcess; port: number }>();
+
+  constructor() {
+    super();
+    mkdirSync(join(dataDir, "jobs"), { recursive: true });
+    for (const id of readdirSync(join(dataDir, "jobs"))) {
+      const f = join(dataDir, "jobs", id, "job.json");
+      if (!existsSync(f)) continue;
+      const job: Job = { ...JSON.parse(readFileSync(f, "utf8")), running: false, previewUrl: undefined };
+      if (!["done", "failed", "waiting"].includes(job.phase)) job.phase = "failed";
+      this.jobs.set(id, job);
+    }
+  }
+
+  // 틀 고르는 화면용. still 은 templates/_shared/previews.ts 가 뽑아 둔 대표 한 장
+  templates() {
+    return listTemplates().map((t) => ({
+      id: t.id,
+      label: t.label,
+      summary: t.summary,
+      aspect: t.aspect,
+      aspects: [t.aspect, ...Object.keys(t.variants ?? {})],
+      width: t.width,
+      height: t.height,
+      duration: t.duration,
+      music: t.music,
+      captions: t.captions,
+      deliverables: t.deliverables,
+      scenes: t.scenes.map((s) => s.id),
+      still: existsSync(templatePreview(t.id)) ? `/api/templates/${t.id}/still.png` : null,
+    }));
+  }
+
+  // 만들기 전에 보여 줄 계획 — 곡 분석 없이 길이·장면 비율만. 사람이 용도를 고르면 판별을 건너뛰고, "auto" 거나 비우면 판별한다.
+  // asks 는 돈이 들거나 없는 생성 능력만(kf make 와 같은 질문) — 페이지가 고른 답을 일에 실어 보낸다
+  async plan(request: string, purpose?: Purpose | "auto", theme?: string): Promise<Plan> {
+    const plan = makePlan({ request, purpose: purpose && purpose !== "auto" ? purpose : undefined, theme });
+    const { questions, auto } = planQuestions(plan, await capabilities({ probe: true }));
+    return { ...plan, asks: questions, answers: auto };
+  }
+
+  // 목록은 approved 만(SPEC 9). all 이면 review·draft 도 — 테마 만드는 사람이 견본을 보는 자리
+  themes(o: { all?: boolean; purpose?: string; aspect?: string } = {}) {
+    const status: ThemeStatus[] = o.all ? ["approved", "review", "draft"] : ["approved"];
+    return themeCards({ status, ...(o.purpose ? { purpose: o.purpose } : {}), ...(o.aspect ? { aspect: o.aspect } : {}) }).map((c) => ({
+      ...c,
+      still: c.still ? `/api/themes/${c.id}/still` : null,
+      sample: c.sample ? `/api/themes/${c.id}/sample` : null,
+    }));
+  }
+
+  themeFile(id: string, which: "still" | "sample"): string | null {
+    return loadTheme(id).files[which];
+  }
+
+  suggest(request: string, purpose: Purpose) {
+    return { candidates: suggestThemes(request, purpose) };
+  }
+
+  // 테마 공장(kf theme) — new 는 뼈대·지시서까지 만들고 그 지시서를 받을 세션 명령을 돌려준다(테마는 그 세션이 만든다).
+  // review 는 굽기라 무겁다 — 하나씩, 진행은 themeTask 로. approve 는 사람이 화면에서 견본을 보고 누를 때만
+  private themeTasks = new Map<string, { running: boolean; log: string[]; code: number | null }>();
+
+  async themeNew(o: { id: string; refs: string[]; name?: string; like?: string; threeD?: boolean }): Promise<{ ok: boolean; command: string | null; log: string[] }> {
+    if (!/^[a-z0-9][a-z0-9-]*$/.test(o.id)) throw Object.assign(new Error("테마 id 는 영문 소문자·숫자·- 만"), { status: 400 });
+    if (!o.refs?.length) throw Object.assign(new Error("참고 자료(refs)가 하나는 있어야 한다"), { status: 400 });
+    const args = ["theme", "new", o.id, ...o.refs.flatMap((r) => ["--ref", r])];
+    if (o.name) args.push("--name", o.name);
+    if (o.like) args.push("--like", o.like);
+    if (o.threeD) args.push("--3d");
+    const { code, log } = await this.kf(args);
+    const at = log.findIndex((l) => l.includes("세션 열기"));
+    return { ok: code === 0, command: at >= 0 ? (log[at + 1]?.trim() ?? null) : null, log };
+  }
+
+  themeReview(id: string): { started: boolean } {
+    const cur = this.themeTasks.get(id);
+    if (cur?.running) throw Object.assign(new Error("이미 굽는 중"), { status: 409 });
+    const task = { running: true, log: [] as string[], code: null as number | null };
+    this.themeTasks.set(id, task);
+    void this.kf(["theme", "review", id, "--tabs", "2"], (l) => task.log.push(l)).then(({ code }) => {
+      task.running = false;
+      task.code = code;
+    });
+    return { started: true };
+  }
+
+  themeTask(id: string) {
+    const t = this.themeTasks.get(id);
+    return t ? { running: t.running, code: t.code, log: t.log.slice(-60) } : { running: false, code: null, log: [] };
+  }
+
+  async themeApprove(id: string) {
+    return this.kf(["theme", "approve", id]);
+  }
+
+  private kf(args: string[], onLine?: (l: string) => void): Promise<{ code: number; log: string[] }> {
+    return new Promise((done) => {
+      const log: string[] = [];
+      const proc = spawn(process.execPath, [kfBin, ...args], { cwd: repo, env: { ...process.env, CLAUDECODE: "" } });
+      for (const stream of [proc.stdout, proc.stderr]) {
+        let buf = "";
+        stream.setEncoding("utf8");
+        stream.on("data", (chunk: string) => {
+          buf += chunk;
+          const parts = buf.split(/\r?\n/);
+          buf = parts.pop() ?? "";
+          for (const l of parts) {
+            log.push(l);
+            onLine?.(l);
+          }
+        });
+      }
+      proc.on("close", (code) => done({ code: code ?? 1, log }));
+    });
+  }
+
+  create(input: JobInput): Job {
+    const id = `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 6)}`;
+    const job: Job = { id, input, dir: join(dataDir, "jobs", id, "project"), phase: "plan", progress: 0, running: false, createdAt: Date.now(), log: [] };
+    this.jobs.set(id, job);
+    mkdirSync(join(dataDir, "jobs", id), { recursive: true });
+    // 모델을 안 고르면 kf make 의 기본 — 고른 모델은 plan.json 에 남아 장면 다시 쓰기가 같은 모델을 부른다
+    const args = ["make", input.request, "--out", job.dir, ...(input.model ? ["--model", input.model] : [])];
+    if (input.purpose && input.purpose !== "auto") args.push("--purpose", input.purpose);
+    if (input.music) args.push("--music", input.music);
+    const given = (input.assets ?? []).filter((a) => existsSync(a));
+    if (given.length) {
+      const inDir = join(dataDir, "jobs", id, "in");
+      mkdirSync(inDir, { recursive: true });
+      for (const a of given) copyFileSync(a, join(inDir, basename(a).replace(/^[a-z0-9]+-/, "")));
+      args.push("--assets", inDir);
+    }
+    if (input.title) args.push("--title", input.title);
+    if (input.theme) args.push("--theme", input.theme);
+    if (input.approve) args.push("--yes");
+    if (input.captions) args.push("--captions", input.captions);
+    // 질문 id 가 곧 kf make 플래그 이름이다(image·video·blender·voice·music)
+    for (const [id, v] of Object.entries(input.answers ?? {})) if (/^[a-z]+$/.test(id) && v) args.push(`--${id}`, v);
+    this.run(job, args);
+    return job;
+  }
+
+  // 장면 카드에서 고친 뒤: 고른 장면만 다시 쓰고(감독 프로젝트는 다시 짓고) 그 조각만 다시 굽고 그 구간만 검사.
+  // 모델은 그 일의 모델 그대로 — 안 정했으면 kf make 가 plan.json 에 남은 모델을 쓴다. pattern·seed 는 감독 후보 고르기
+  rewrite(id: string, scenes: string[], o: { pattern?: Record<string, string>; seed?: Record<string, string> } = {}): Job {
+    const job = this.must(id);
+    if (!scenes.length) throw Object.assign(new Error("다시 쓸 장면이 없다"), { status: 400 });
+    const pairs = (m?: Record<string, string>) => Object.entries(m ?? {}).filter(([k, v]) => scenes.includes(k) && v).map(([k, v]) => `${k}=${v}`).join(",");
+    const args = ["make", "--rewrite", job.dir, "--scenes", scenes.join(",")];
+    if (job.input.model) args.push("--model", job.input.model);
+    if (pairs(o.pattern)) args.push("--pattern", pairs(o.pattern));
+    if (pairs(o.seed)) args.push("--scene-seed", pairs(o.seed));
+    this.focusOn(job, scenes);
+    this.run(job, args);
+    return job;
+  }
+
+  // 장면 파일은 그대로, 바뀐 조각만 다시 굽고 그 구간만 검사 — 손으로 고친 장면·바꾼 자산
+  redo(id: string, scenes: string[]): Job {
+    const job = this.must(id);
+    if (!scenes.length) throw Object.assign(new Error("다시 구울 장면이 없다"), { status: 400 });
+    this.focusOn(job, scenes);
+    this.run(job, ["make", "--finish", job.dir, "--scenes", scenes.join(","), "--fix", "0"]);
+    return job;
+  }
+
+  // captions 를 주면 장면을 다시 쓰지 않고 자막만 켜고(끄고) 따로 굽는다 — 원본 video.mp4 는 그대로 두고 -자막 판을 옆에
+  rerender(id: string, o: { captions?: "on" | "off" } = {}): Job {
+    const job = this.must(id);
+    const caps = o.captions === "on" || o.captions === "off" ? ["--captions", o.captions, "--suffix"] : [];
+    this.run(job, ["make", "--finish", job.dir, "--fix", "0", ...caps]);
+    return job;
+  }
+
+  private focusOn(job: Job, scenes: string[]): void {
+    job.focus = scenes[0];
+    job.scenes = Object.fromEntries(Object.entries(job.scenes ?? {}).filter(([k]) => !scenes.includes(k)));
+  }
+
+  private sceneLine(job: Job, line: string): void {
+    const m = line.match(SCENE_LINE);
+    if (!m) return;
+    (job.scenes ??= {})[m[1]] = { state: SCENE_WORDS[m[2]], ...(m[3] ? { note: m[3].trim() } : {}), at: Date.now() };
+  }
+
+  // 장면 하나 고치는 자리 — 감독 프로젝트는 content.json 의 그 장면 칸·패턴 후보·씨앗, 아니면 할 일·장면 모델. 자산은 그 장면이 쓰는 그림·영상
+  sceneDetail(id: string, sid: string): SceneDetail {
+    const job = this.must(id);
+    const read = (f: string) => (existsSync(join(job.dir, f)) ? JSON.parse(readFileSync(join(job.dir, f), "utf8")) : null);
+    const kf = read("kf.json");
+    const scene = kf?.scenes?.find((s: { id: string }) => s.id === sid);
+    if (!scene) throw Object.assign(new Error(`장면 ${sid} 가 없다`), { status: 404 });
+    const plan = read("plan.json") ?? {};
+    const director = read("director.json");
+    const ds = director?.scenes?.find((s: { id: string }) => s.id === sid);
+    const file = join(job.dir, scene.file ?? `scenes/${sid}.ts`);
+    const src = existsSync(file) ? readFileSync(file, "utf8") : "";
+    const assetsDir = join(job.dir, "assets");
+    const walk = (d: string): string[] => (existsSync(d) ? readdirSync(d, { withFileTypes: true }).flatMap((e) => (e.isDirectory() ? walk(join(d, e.name)) : [join(d, e.name)])) : []);
+    const assets = walk(assetsDir)
+      .filter((f) => /\.(png|jpe?g|webp|gif|mp4|webm|mov)$/i.test(f))
+      .map((f) => relative(assetsDir, f).split(sep).join("/"))
+      .filter((rel) => src.includes(rel) || basename(rel).startsWith(`${sid}.`) || basename(rel).startsWith(`${sid}-`))
+      .map((rel) => ({ path: rel, url: `/api/jobs/${id}/files/assets/${rel}`, kind: (/\.(mp4|webm|mov)$/i.test(rel) ? "video" : "image") as "image" | "video" }));
+    return {
+      scene,
+      direct: plan.direct === true,
+      model: job.input.model ?? plan.model ?? null,
+      content: read("content.json")?.scenes?.find((s: { id: string }) => s.id === sid) ?? null,
+      pattern: ds?.pattern ?? null,
+      candidates: ds?.order ?? [],
+      pinned: director?.pinned?.[sid] ?? null,
+      assets,
+    };
+  }
+
+  // 사람이 올린 파일로 그 장면 자산 하나를 바꾼다 — 다음 굽기에서 그 자산을 쓰는 조각만 다시 찍힌다
+  replaceAsset(id: string, sid: string, o: { path: string; upload: string }): SceneDetail {
+    const job = this.must(id);
+    const detail = this.sceneDetail(id, sid);
+    if (!detail.assets.some((a) => a.path === o.path)) throw Object.assign(new Error(`장면 ${sid} 가 쓰는 자산이 아니다: ${o.path}`), { status: 400 });
+    if (!existsSync(o.upload)) throw Object.assign(new Error("올린 파일이 없다"), { status: 400 });
+    if (extname(o.upload).toLowerCase() !== extname(o.path).toLowerCase()) throw Object.assign(new Error(`같은 꼴(${extname(o.path)})로 올린다`), { status: 400 });
+    copyFileSync(o.upload, join(job.dir, "assets", o.path));
+    return this.sceneDetail(id, sid);
+  }
+
+  // 말로 시작한 kf make(Claude Code 등)가 스스로 등록한다 — 같은 폴더면 같은 일(--finish 가 다시 붙는다)
+  attach(o: { dir: string; request: string; model?: string; purpose?: Purpose }): Job {
+    const dir = resolve(o.dir);
+    const had = [...this.jobs.values()].find((j) => j.dir === dir);
+    if (had) return had;
+    const id = `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 6)}`;
+    const job: Job = { id, external: true, input: { request: o.request, model: o.model, purpose: o.purpose }, dir, phase: "scaffold", progress: 0, running: true, createdAt: Date.now(), log: [] };
+    this.jobs.set(id, job);
+    mkdirSync(join(dataDir, "jobs", id), { recursive: true });
+    if (existsSync(join(dir, "kf.json"))) this.startPreview(job);
+    this.save(job);
+    this.emit("state", this.view(id));
+    return job;
+  }
+
+  progress(id: string, p: { lines?: string[]; phase?: Phase; done?: boolean; ok?: boolean }): void {
+    const job = this.must(id);
+    for (const line of p.lines ?? []) {
+      job.log.push(line);
+      this.sceneLine(job, line);
+      for (const [re, phase] of PHASES) if (re.test(line)) job.phase = phase;
+      const pct = line.match(/\((\d+)%\)/);
+      if (pct && job.phase === "render") job.progress = Number(pct[1]) / 100;
+      this.emit("log", id, line);
+    }
+    if (job.log.length > 800) job.log.splice(0, job.log.length - 800);
+    if (p.phase) job.phase = p.phase;
+    job.running = !p.done;
+    if (p.done) {
+      job.checkPassed = !!p.ok;
+      job.phase = p.phase ?? (existsSync(join(job.dir, "out", "video.mp4")) ? "done" : "failed");
+      this.stopPreview(job);
+    } else if (!job.previewUrl && existsSync(join(job.dir, "kf.json"))) this.startPreview(job);
+    this.save(job);
+    this.emit("state", this.view(id));
+  }
+
+  editScene(id: string, sceneId: string, patch: { idea?: string; dur?: number; content?: Record<string, unknown> }): unknown {
+    const job = this.must(id);
+    // 감독 프로젝트 — 화면에 보일 것은 content.json 이 정본이다. 칸이 틀리면 저장하지 않고 어느 칸인지 돌려준다
+    if (patch.content) {
+      const cPath = join(job.dir, "content.json");
+      if (!existsSync(cPath)) throw Object.assign(new Error("content.json 이 없다 — 감독 모드로 만든 일이 아니다"), { status: 400 });
+      const content = JSON.parse(readFileSync(cPath, "utf8"));
+      const at = content.scenes?.findIndex((s: { id: string }) => s.id === sceneId) ?? -1;
+      if (at < 0) throw Object.assign(new Error(`content.json 에 장면 ${sceneId} 가 없다`), { status: 404 });
+      content.scenes[at] = { ...patch.content, id: sceneId };
+      const c = checkContent(content);
+      if (c.errors.length) throw Object.assign(new Error(c.errors.map((e) => `${e.at}: ${e.msg}`).join("\n")), { status: 400 });
+      writeFileSync(cPath, `${JSON.stringify(content, null, 2)}\n`);
+    }
+    const kfPath = join(job.dir, "kf.json");
+    const kf = JSON.parse(readFileSync(kfPath, "utf8"));
+    const i = kf.scenes.findIndex((s: { id: string }) => s.id === sceneId);
+    if (i < 0) throw new Error(`장면 ${sceneId} 가 없다`);
+    if (patch.idea !== undefined) kf.scenes[i].idea = patch.idea;
+    // 시간표는 빈틈 없이 이어져야 한다(계약 6) — 길이를 바꾸면 다음 장면 시작이 따라 움직인다
+    if (patch.dur !== undefined && i < kf.scenes.length - 1) {
+      const next = kf.scenes[i + 1];
+      const end = next.from + next.dur;
+      const dur = Math.round(Math.max(0.5, Math.min(patch.dur, end - kf.scenes[i].from - 0.5)) * kf.fps) / kf.fps;
+      kf.scenes[i].dur = +dur.toFixed(4);
+      next.from = +(kf.scenes[i].from + dur).toFixed(4);
+      next.dur = +(end - next.from).toFixed(4);
+    }
+    writeFileSync(kfPath, `${JSON.stringify(kf, null, 2)}\n`);
+    const planPath = join(job.dir, "plan.json");
+    if (existsSync(planPath) && patch.idea !== undefined) {
+      const plan = JSON.parse(readFileSync(planPath, "utf8"));
+      const s = plan.scenes?.find((x: { id: string }) => x.id === sceneId);
+      if (s) s.idea = patch.idea;
+      writeFileSync(planPath, `${JSON.stringify(plan, null, 2)}\n`);
+    }
+    this.emit("state", this.view(id));
+    return kf;
+  }
+
+  view(id: string): JobView {
+    const job = this.must(id);
+    const read = (f: string) => (existsSync(join(job.dir, f)) ? JSON.parse(readFileSync(join(job.dir, f), "utf8")) : undefined);
+    const has = (f: string) => (existsSync(join(job.dir, f)) ? f : undefined);
+    const { log: _log, ...rest } = job;
+    const kf = read("kf.json");
+    const alt = has(captionMode(kf?.captions) === "on" ? "out/video-자막없음.mp4" : "out/video-자막.mp4");
+    const video = has("out/video.mp4");
+    // 같은 이름으로 다시 구워도 화면이 새 영상을 받게 — 고친 시각을 붙인다
+    const videoAt = video ? Math.round(statSync(join(job.dir, video)).mtimeMs) : undefined;
+    return { ...rest, plan: read("plan.json"), kf, files: { video, cover: has("out/cover.png"), check: has("out/check.json"), alt, captions: has("captions.json"), videoAt } };
+  }
+
+  list(): JobView[] {
+    return [...this.jobs.keys()].map((id) => this.view(id)).sort((a, b) => b.createdAt - a.createdAt);
+  }
+
+  logOf(id: string): string[] {
+    return this.must(id).log;
+  }
+
+  stop(id: string): void {
+    this.procs.get(id)?.kill("SIGTERM");
+  }
+
+  async close(): Promise<void> {
+    for (const p of this.procs.values()) p.kill("SIGTERM");
+    for (const p of this.previews.values()) p.proc.kill("SIGTERM");
+  }
+
+  private must(id: string): Job {
+    const job = this.jobs.get(id);
+    if (!job) throw Object.assign(new Error(`일 ${id} 가 없다`), { status: 404 });
+    return job;
+  }
+
+  private run(job: Job, args: string[]): void {
+    if (job.running) throw Object.assign(new Error("이미 돌고 있다"), { status: 409 });
+    job.running = true;
+    job.error = undefined;
+    job.progress = 0;
+    const proc = spawn(process.execPath, [kfBin, ...args], { cwd: repo, env: { ...process.env, CLAUDECODE: "" } });
+    this.procs.set(job.id, proc);
+    const onLine = (line: string) => {
+      if (!line.trim()) return;
+      job.log.push(line);
+      if (job.log.length > 800) job.log.splice(0, job.log.length - 800);
+      this.sceneLine(job, line);
+      for (const [re, phase] of PHASES) if (re.test(line)) job.phase = phase;
+      const pct = line.match(/\((\d+)%\)/);
+      if (pct && job.phase === "render") job.progress = Number(pct[1]) / 100;
+      if (/^검사:/.test(line)) job.phase = "check";
+      this.emit("log", job.id, line);
+      if (!job.previewUrl && existsSync(join(job.dir, "kf.json"))) this.startPreview(job);
+      this.emit("state", this.view(job.id));
+    };
+    for (const stream of [proc.stdout, proc.stderr]) {
+      let buf = "";
+      stream.setEncoding("utf8");
+      stream.on("data", (chunk: string) => {
+        buf += chunk;
+        const parts = buf.split(/\r?\n|\r/);
+        buf = parts.pop() ?? "";
+        parts.forEach(onLine);
+      });
+    }
+    proc.on("close", (code) => {
+      this.procs.delete(job.id);
+      job.running = false;
+      // 다 만들었으면 화면은 MP4 를 튼다 — 미리보기 서버는 꺼서 기계 부하를 줄인다(다시 보려면 /preview 가 다시 띄운다)
+      this.stopPreview(job);
+      job.checkPassed = code === 0;
+      if (code === 0) job.phase = "done";
+      else if (code === 3) job.phase = "waiting";
+      else {
+        job.phase = existsSync(join(job.dir, "out", "video.mp4")) ? "done" : "failed";
+        job.error = job.log.slice(-6).join("\n");
+      }
+      job.progress = job.phase === "done" ? 1 : job.progress;
+      this.save(job);
+      this.emit("state", this.view(job.id));
+    });
+    this.save(job);
+  }
+
+  // 만드는 동안 장면 파일이 쓰일 때마다 미리보기가 저절로 새로 고쳐진다(kf preview 의 감시)
+  private startPreview(job: Job): void {
+    if (this.previews.has(job.id)) return;
+    const used = new Set([...this.previews.values()].map((p) => p.port));
+    let port = PREVIEW_PORTS.find((p) => !used.has(p));
+    if (port === undefined) {
+      const [oldest] = this.previews.keys();
+      const old = this.previews.get(oldest)!;
+      old.proc.kill("SIGTERM");
+      this.previews.delete(oldest);
+      const j = this.jobs.get(oldest);
+      if (j) j.previewUrl = undefined;
+      port = old.port;
+    }
+    const proc = spawn(process.execPath, [kfBin, "preview", job.dir, "--port", String(port)], { cwd: repo, stdio: ["ignore", "pipe", "pipe"] });
+    this.previews.set(job.id, { proc, port });
+    job.previewUrl = `http://127.0.0.1:${port}/`;
+    const grab = (chunk: Buffer) => {
+      const m = chunk.toString().match(/https?:\/\/[^\s]+/);
+      if (m) {
+        job.previewUrl = m[0];
+        this.emit("state", this.view(job.id));
+      }
+    };
+    proc.stdout?.on("data", grab);
+    proc.stderr?.on("data", grab);
+    proc.on("close", () => {
+      if (this.previews.get(job.id)?.proc === proc) this.previews.delete(job.id);
+    });
+  }
+
+  private stopPreview(job: Job): void {
+    const p = this.previews.get(job.id);
+    if (!p) return;
+    p.proc.kill("SIGTERM");
+    this.previews.delete(job.id);
+    job.previewUrl = undefined;
+  }
+
+  previewFor(id: string): string | undefined {
+    const job = this.must(id);
+    if (!job.previewUrl && existsSync(join(job.dir, "kf.json"))) this.startPreview(job);
+    return job.previewUrl;
+  }
+
+  private save(job: Job): void {
+    const { previewUrl: _p, running: _r, ...rest } = job;
+    writeFileSync(join(dataDir, "jobs", job.id, "job.json"), `${JSON.stringify(rest, null, 2)}\n`);
+  }
+}