aimakeall-mcp 0.1.0

package/lib/companion-client.mjs

@@ -0,0 +1,153 @@
+import { createWriteStream, existsSync, mkdirSync, renameSync, rmSync, statSync } from "node:fs";
+import path from "node:path";
+import { Readable } from "node:stream";
+import { pipeline } from "node:stream/promises";
+
+import { sanitizeOutputFilename } from "./payload-guard.mjs";
+
+// 로컬 컴패니언(127.0.0.1:9876) 클라이언트 — 웹 프런트의 renderJobClient 계약을 따른다.
+// 비브라우저 클라이언트는 Origin 헤더를 보내지 않아야 컴패니언 게이트를 그대로 통과한다.
+
+const DEFAULT_TIMEOUT_MS = 15_000;
+const DOWNLOAD_TIMEOUT_MS = 10 * 60_000;
+
+async function requestJson(baseUrl, pathName, { method = "GET", body, timeoutMs = DEFAULT_TIMEOUT_MS } = {}) {
+  const response = await fetch(`${baseUrl}${pathName}`, {
+    body: body === undefined ? undefined : JSON.stringify(body),
+    headers: body === undefined ? {} : { "Content-Type": "application/json" },
+    method,
+    signal: AbortSignal.timeout(timeoutMs),
+  });
+  const text = await response.text();
+  let payload = null;
+  try {
+    payload = text ? JSON.parse(text) : null;
+  } catch {
+    payload = null;
+  }
+  return { payload, status: response.status };
+}
+
+export async function getCompanionHealth(companionUrl) {
+  return requestJson(companionUrl, "/health");
+}
+
+export async function getMoviePyHealth(companionUrl) {
+  // moviepy 헬스는 파이썬 프로브를 돌리므로 여유 있게.
+  return requestJson(companionUrl, "/api/moviepy/health", { timeoutMs: 60_000 });
+}
+
+// 컴패니언 상태를 4가지로 진단 — 상태별로 다른 안내를 내보내기 위함.
+// 반환: { state: "ready"|"not-running"|"port-conflict"|"runtime-missing", detail }
+export async function triageCompanion(companionUrl) {
+  let health;
+  try {
+    health = await getCompanionHealth(companionUrl);
+  } catch (error) {
+    return { detail: String(error?.cause?.code || error?.message || error), state: "not-running" };
+  }
+  const app = String(health.payload?.app || "");
+  if (!health.payload?.ok || !app.includes("Companion")) {
+    return { detail: `9876 포트 응답이 컴패니언이 아님 (app=${app || "?"})`, state: "port-conflict" };
+  }
+  let moviepy;
+  try {
+    moviepy = await getMoviePyHealth(companionUrl);
+  } catch (error) {
+    return { detail: String(error?.message || error), state: "runtime-missing" };
+  }
+  if (!moviepy.payload?.ok || moviepy.payload?.moviepy?.available !== true) {
+    return {
+      detail: String(moviepy.payload?.moviepy?.reason || "MoviePy 런타임을 찾지 못했습니다."),
+      state: "runtime-missing",
+    };
+  }
+  return {
+    detail: `moviepy ${moviepy.payload.moviepy.version} (${moviepy.payload.moviepy.label})`,
+    state: "ready",
+    version: String(health.payload?.version || ""),
+  };
+}
+
+export async function createRenderJob(companionUrl, payload) {
+  return requestJson(companionUrl, "/api/moviepy/render-jobs", {
+    body: payload,
+    method: "POST",
+    timeoutMs: 60_000,
+  });
+}
+
+export async function getRenderJob(companionUrl, jobId) {
+  return requestJson(companionUrl, `/api/moviepy/render-jobs/${encodeURIComponent(String(jobId || ""))}`);
+}
+
+// Content-Disposition 에서 파일명 추출 — filename*=UTF-8'' 우선, 없으면 filename=.
+export function parseContentDispositionFilename(headerValue) {
+  const raw = String(headerValue || "");
+  const star = raw.match(/filename\*=UTF-8''([^;]+)/iu);
+  if (star) {
+    try {
+      return decodeURIComponent(star[1].trim());
+    } catch {
+      // fall through
+    }
+  }
+  const plain = raw.match(/filename="?([^";]+)"?/iu);
+  return plain ? plain[1].trim() : "";
+}
+
+/**
+ * 완료된 잡의 mp4 를 스트리밍으로 저장 — .part 로 받아 원자적 rename.
+ * 성공 시 컴패니언이 파일을 삭제(1회성)하므로 저장 성공 후에만 소비된 것으로 본다.
+ * 반환: { filePath, bytes } 또는 { error, status }
+ */
+// 사용된 파일명이 이미 있으면 -2, -3 … 을 붙여 기존 출력을 덮어쓰지 않는다.
+function uniqueOutputPath(dir, fileName) {
+  const ext = path.extname(fileName);
+  const base = fileName.slice(0, fileName.length - ext.length);
+  let candidate = path.join(dir, fileName);
+  let counter = 2;
+  while (existsSync(candidate)) {
+    candidate = path.join(dir, `${base}-${counter}${ext}`);
+    counter += 1;
+  }
+  return candidate;
+}
+
+export async function downloadRenderOutput(companionUrl, jobId, outputDir, { suggestedName = "" } = {}) {
+  let response;
+  try {
+    response = await fetch(
+      `${companionUrl}/api/moviepy/render-jobs/${encodeURIComponent(String(jobId || ""))}/output`,
+      { signal: AbortSignal.timeout(DOWNLOAD_TIMEOUT_MS) },
+    );
+  } catch (error) {
+    return { error: `출력 다운로드 중 컴패니언 연결 오류: ${String(error?.message || error)}`, status: 0 };
+  }
+  if (!response.ok) {
+    let detail = "";
+    try {
+      detail = JSON.parse(await response.text())?.error || "";
+    } catch {
+      // ignore
+    }
+    return { error: detail || `출력 다운로드 실패 (HTTP ${response.status})`, status: response.status };
+  }
+
+  const headerName = parseContentDispositionFilename(response.headers.get("content-disposition"));
+  let fileName = sanitizeOutputFilename(suggestedName || headerName, `render-${jobId}.mp4`);
+  if (!/\.[A-Za-z0-9]{1,5}$/u.test(fileName)) fileName += ".mp4"; // 확장자 없으면 mp4 보정
+  mkdirSync(outputDir, { recursive: true });
+  const finalPath = uniqueOutputPath(outputDir, fileName);
+  const partPath = `${finalPath}.part`;
+
+  try {
+    await pipeline(Readable.fromWeb(response.body), createWriteStream(partPath, { mode: 0o600 }));
+    renameSync(partPath, finalPath);
+  } catch (error) {
+    // 중단 시 부분 파일 정리 — 잡은 다운로드 실패로 남아 재시도 가능(네트워크 abort 시 서버가 복구).
+    try { rmSync(partPath, { force: true }); } catch { /* ignore */ }
+    return { error: `출력 저장 중 오류: ${String(error?.message || error)} — render_status로 상태 확인 후 다시 시도하세요.`, status: 0 };
+  }
+  return { bytes: statSync(finalPath).size, filePath: finalPath };
+}

package/lib/companion-tools.mjs

@@ -0,0 +1,210 @@
+import { z } from "zod";
+
+import {
+  createRenderJob,
+  downloadRenderOutput,
+  getRenderJob,
+  triageCompanion,
+} from "./companion-client.mjs";
+import { detectRemoteEnvironment } from "./config.mjs";
+import { readPayloadHandle } from "./media-store.mjs";
+import {
+  checkRenderPayloadSize,
+  sanitizeRenderPayload,
+} from "./payload-guard.mjs";
+import {
+  listRenderJobs,
+  recordRenderJob,
+  updateRenderJob,
+} from "./render-job-store.mjs";
+
+// 컴패니언(로컬 렌더) 관련 MCP 툴 — 렌더는 100% 사용자 PC에서 수행된다.
+
+function textResult(text, { isError = false } = {}) {
+  return { content: [{ text, type: "text" }], ...(isError ? { isError: true } : {}) };
+}
+
+// 컴패니언 미기동 4상태별 안내 — 리뷰에서 확정한 트리아지.
+export function describeCompanionState(triage, remoteEnv) {
+  if (triage.state === "ready") return `컴패니언 정상 (${triage.detail})`;
+  if (triage.state === "not-running") {
+    if (remoteEnv === "ssh") {
+      return "이 세션은 원격(SSH)입니다. 로컬 PC에서 컴패니언을 실행한 뒤 터널을 여세요: ssh -R 9876:127.0.0.1:9876 <이 서버>";
+    }
+    if (remoteEnv === "wsl") {
+      return "WSL에서는 127.0.0.1이 Windows 호스트와 분리됩니다. Windows에서 컴패니언을 실행하고 WSL mirrored 네트워킹을 켜거나, AIMAKEALL_COMPANION_URL로 접근 가능한 주소를 지정하세요.";
+    }
+    return "AImakeAll 컴패니언이 실행 중이 아닙니다. aimakeall.com에서 컴패니언 앱을 설치·실행한 뒤 다시 시도하세요.";
+  }
+  if (triage.state === "port-conflict") {
+    return `9876 포트를 다른 프로그램이 사용 중입니다 (${triage.detail}). 해당 프로그램을 종료하거나 컴패니언 포트를 확인하세요.`;
+  }
+  return `컴패니언은 실행 중이지만 렌더 런타임이 없습니다 (${triage.detail}). 컴패니언 앱에서 렌더 런타임 설치를 실행하세요.`;
+}
+
+export function registerCompanionTools(server, config) {
+  const remoteEnv = detectRemoteEnvironment();
+
+  server.tool(
+    "companion_status",
+    "로컬 렌더 컴패니언(사용자 PC)의 상태를 진단합니다. 렌더 작업 전에 먼저 호출하세요.",
+    {},
+    async () => {
+      const triage = await triageCompanion(config.companionUrl);
+      const guidance = describeCompanionState(triage, remoteEnv);
+      return textResult(JSON.stringify({ detail: triage.detail, guidance, state: triage.state }, null, 2), {
+        isError: triage.state !== "ready",
+      });
+    },
+  );
+
+  server.tool(
+    "render_start",
+    "타임라인 페이로드를 로컬 컴패니언에 제출해 mp4 렌더를 시작합니다. stitch_timeline이 반환한 payloadPath를 넘기는 것이 표준 경로입니다. 즉시 jobId를 반환하며, render_status로 폴링하고 render_result로 파일을 저장하세요. 렌더는 이 PC에서 수행됩니다.",
+    {
+      payloadPath: z.string().optional().describe("stitch_timeline이 반환한 매니페스트 파일 경로 (권장)"),
+      payload: z.record(z.any()).optional().describe("타임라인 페이로드 객체를 직접 전달 (소형일 때만)"),
+      projectTitle: z.string().optional().describe("잡 라벨용 프로젝트 이름"),
+    },
+    async ({ payloadPath, payload, projectTitle }) => {
+      const triage = await triageCompanion(config.companionUrl);
+      if (triage.state !== "ready") {
+        return textResult(describeCompanionState(triage, remoteEnv), { isError: true });
+      }
+
+      let resolvedPayload = payload;
+      if (payloadPath) {
+        try {
+          // stateDir/media 안의 핸들만 허용 — 임의 로컬 JSON 파일 읽기 차단.
+          resolvedPayload = readPayloadHandle(payloadPath, { stateDir: config.stateDir });
+        } catch (error) {
+          return textResult(`payloadPath를 읽지 못했습니다: ${String(error?.message || error)}`, { isError: true });
+        }
+      }
+      if (!resolvedPayload || typeof resolvedPayload !== "object") {
+        return textResult("payloadPath 또는 payload 중 하나는 필요합니다.", { isError: true });
+      }
+
+      const { payload: cleaned, warnings } = sanitizeRenderPayload(resolvedPayload);
+      const size = checkRenderPayloadSize(cleaned);
+      if (!size.ok) {
+        return textResult(
+          `렌더 페이로드가 컴패니언 상한(32MB)을 초과합니다 (${Math.round(size.bytes / 1024 / 1024)}MB). 영상을 나눠서 렌더하세요.`,
+          { isError: true },
+        );
+      }
+
+      let result;
+      try {
+        result = await createRenderJob(config.companionUrl, cleaned);
+      } catch (error) {
+        return textResult(`컴패니언 렌더 요청 실패: ${String(error?.message || error)} — 컴패니언이 실행 중인지 확인하세요.`, { isError: true });
+      }
+      if (result.status === 429) {
+        return textResult(
+          "다른 렌더(웹 스튜디오 포함)가 이미 대기열에 있습니다. 끝난 뒤 다시 시도하세요.",
+          { isError: true },
+        );
+      }
+      if (result.status >= 400 || !result.payload?.jobId) {
+        return textResult(
+          `렌더 잡 생성 실패 (HTTP ${result.status}): ${result.payload?.error || "알 수 없는 오류"}`,
+          { isError: true },
+        );
+      }
+
+      // 잡 영속화는 복구용 best-effort — 실패해도 jobId 는 반드시 반환한다.
+      try {
+        recordRenderJob(config.stateDir, {
+          jobId: result.payload.jobId,
+          outputUrl: result.payload.outputUrl || "",
+          projectTitle: projectTitle || String(resolvedPayload?.projectTitle || ""),
+          statusUrl: result.payload.statusUrl || "",
+        });
+      } catch {
+        // 영속화 실패는 무시
+      }
+
+      return textResult(JSON.stringify({
+        jobId: result.payload.jobId,
+        next: "render_status로 진행률을 폴링하세요 (2~5초 간격 권장).",
+        status: result.payload.status || "queued",
+        warnings,
+      }, null, 2));
+    },
+  );
+
+  server.tool(
+    "render_status",
+    "렌더 잡의 진행률(percent/eta/stage)을 조회합니다.",
+    { jobId: z.string().describe("render_start가 반환한 jobId") },
+    async ({ jobId }) => {
+      let result;
+      try {
+        result = await getRenderJob(config.companionUrl, jobId);
+      } catch (error) {
+        return textResult(`컴패니언 상태 조회 실패: ${String(error?.message || error)} — 컴패니언이 실행 중인지 확인하세요.`, { isError: true });
+      }
+      if (result.status === 404) {
+        return textResult(
+          "잡을 찾을 수 없습니다. 컴패니언이 재시작되어 잡이 사라졌을 수 있습니다 — render_start로 다시 시작하세요. (list_render_jobs로 이 PC에서 시작한 잡 목록을 볼 수 있습니다)",
+          { isError: true },
+        );
+      }
+      if (result.status >= 400) {
+        return textResult(`상태 조회 실패 (HTTP ${result.status})`, { isError: true });
+      }
+      const job = result.payload || {};
+      try {
+        updateRenderJob(config.stateDir, jobId, { status: job.status || "" });
+      } catch {
+        // 영속화 실패는 무시
+      }
+      return textResult(JSON.stringify({
+        etaSec: job.progress?.etaSec ?? null,
+        percent: job.progress?.percent ?? 0,
+        stage: job.stage || "",
+        status: job.status || "",
+      }, null, 2));
+    },
+  );
+
+  server.tool(
+    "render_result",
+    "완료된 렌더 잡의 mp4를 이 PC의 출력 폴더에 저장하고 절대 경로를 반환합니다. 출력은 1회성입니다(저장 성공 후 컴패니언에서 삭제됨).",
+    {
+      jobId: z.string().describe("render_start가 반환한 jobId"),
+      fileName: z.string().optional().describe("저장할 파일명 (생략 시 서버 제안 이름)"),
+    },
+    async ({ jobId, fileName }) => {
+      const saved = await downloadRenderOutput(config.companionUrl, jobId, config.outputDir, {
+        suggestedName: fileName || "",
+      });
+      if (saved.error) {
+        const hint = saved.status === 409
+          ? " (아직 렌더가 진행 중입니다 — render_status로 완료를 확인한 뒤 다시 호출하세요)"
+          : saved.status === 410
+            ? " (잡이 만료되어 출력이 삭제되었습니다 — render_start로 다시 렌더하세요)"
+            : "";
+        return textResult(`${saved.error}${hint}`, { isError: true });
+      }
+      try {
+        updateRenderJob(config.stateDir, jobId, { filePath: saved.filePath, status: "downloaded" });
+      } catch {
+        // 영속화 실패는 무시
+      }
+      return textResult(JSON.stringify({
+        bytes: saved.bytes,
+        filePath: saved.filePath,
+        note: "파일은 이 PC에 저장되었습니다.",
+      }, null, 2));
+    },
+  );
+
+  server.tool(
+    "list_render_jobs",
+    "이 PC에서 최근 24시간 내 시작한 렌더 잡 목록(프록시 재시작 후 복구용)을 보여줍니다.",
+    {},
+    async () => textResult(JSON.stringify({ jobs: listRenderJobs(config.stateDir) }, null, 2)),
+  );
+}

package/lib/config.mjs

@@ -0,0 +1,41 @@
+import { homedir } from "node:os";
+import path from "node:path";
+
+// 프록시 버전 — 서버가 X-AImakeAll-MCP-Version 으로 하한을 강제(426)할 수 있다.
+export const MCP_PROXY_VERSION = "0.1.0";
+
+export const DEFAULT_API_BASE = "https://aimakeall.com";
+export const DEFAULT_COMPANION_URL = "http://127.0.0.1:9876";
+
+// PAT 형식 사전 검증 — 잘못 복사한 값으로 서버에 무의미한 401 트래픽을 만들지 않는다.
+export const PAT_PATTERN = /^aio_pat_[A-Za-z0-9_-]{40,64}$/;
+
+export function resolveConfig(env = process.env) {
+  const pat = String(env.AIMAKEALL_PAT || "").trim();
+  const apiBase = (String(env.AIMAKEALL_API_BASE || "").trim() || DEFAULT_API_BASE).replace(/\/+$/, "");
+  const companionUrl = (String(env.AIMAKEALL_COMPANION_URL || "").trim() || DEFAULT_COMPANION_URL).replace(/\/+$/, "");
+  const outputDir = String(env.AIMAKEALL_OUTPUT_DIR || "").trim()
+    || path.join(homedir(), "Downloads", "AImakeAll");
+  const stateDir = path.join(homedir(), ".aimakeall");
+
+  return {
+    apiBase,
+    companionUrl,
+    outputDir,
+    pat,
+    patLooksValid: PAT_PATTERN.test(pat),
+    stateDir,
+    version: MCP_PROXY_VERSION,
+  };
+}
+
+// 원격/컨테이너 환경 감지 — 컴패니언 부재 시 설치 안내 대신 SSH 터널 안내를 내보낸다.
+export function detectRemoteEnvironment(env = process.env) {
+  if (String(env.SSH_CONNECTION || "").trim() || String(env.SSH_TTY || "").trim()) {
+    return "ssh";
+  }
+  if (String(env.WSL_DISTRO_NAME || "").trim()) {
+    return "wsl";
+  }
+  return "";
+}

package/lib/config.test.mjs

@@ -0,0 +1,43 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { detectRemoteEnvironment, resolveConfig } from "./config.mjs";
+import { parseContentDispositionFilename } from "./companion-client.mjs";
+
+test("기본값 — API base·컴패니언 URL·출력 디렉터리", () => {
+  const config = resolveConfig({});
+  assert.equal(config.apiBase, "https://aimakeall.com");
+  assert.equal(config.companionUrl, "http://127.0.0.1:9876");
+  assert.ok(config.outputDir.endsWith("AImakeAll"));
+  assert.equal(config.pat, "");
+  assert.equal(config.patLooksValid, false);
+});
+
+test("env 오버라이드 + 후행 슬래시 정리 + PAT 형식 판정", () => {
+  const config = resolveConfig({
+    AIMAKEALL_API_BASE: "https://staging.example.com///",
+    AIMAKEALL_COMPANION_URL: "http://127.0.0.1:19876/",
+    AIMAKEALL_PAT: "aio_pat_0123456789012345678901234567890123456789",
+  });
+  assert.equal(config.apiBase, "https://staging.example.com");
+  assert.equal(config.companionUrl, "http://127.0.0.1:19876");
+  assert.equal(config.patLooksValid, true);
+  assert.equal(resolveConfig({ AIMAKEALL_PAT: "sk-wrong-kind" }).patLooksValid, false);
+});
+
+test("원격 환경 감지 — ssh/wsl/로컬", () => {
+  assert.equal(detectRemoteEnvironment({ SSH_CONNECTION: "1.2.3.4 5 6.7.8.9 22" }), "ssh");
+  assert.equal(detectRemoteEnvironment({ SSH_TTY: "/dev/pts/0" }), "ssh");
+  assert.equal(detectRemoteEnvironment({ WSL_DISTRO_NAME: "Ubuntu" }), "wsl");
+  assert.equal(detectRemoteEnvironment({}), "");
+});
+
+test("Content-Disposition 파일명 파싱 — RFC5987 우선, 따옴표 폴백", () => {
+  assert.equal(
+    parseContentDispositionFilename("attachment; filename*=UTF-8''%EC%98%81%EC%83%81.mp4"),
+    "영상.mp4",
+  );
+  assert.equal(parseContentDispositionFilename('attachment; filename="out.mp4"'), "out.mp4");
+  assert.equal(parseContentDispositionFilename("attachment; filename=plain.mp4"), "plain.mp4");
+  assert.equal(parseContentDispositionFilename(""), "");
+});

package/lib/media-store.mjs

@@ -0,0 +1,136 @@
+import { randomUUID } from "node:crypto";
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import path from "node:path";
+
+import { sanitizeOutputFilename } from "./payload-guard.mjs";
+
+// 로컬 미디어 스테이징 — TTS 오디오·스티치 매니페스트 같은 대용량 산출물은
+// MCP 툴 결과(모델 컨텍스트)로 돌려주지 않고 파일 경로 핸들로 주고받는다.
+
+const MIME_BY_EXT = new Map([
+  [".jpeg", "image/jpeg"],
+  [".jpg", "image/jpeg"],
+  [".json", "application/json"],
+  [".mp3", "audio/mpeg"],
+  [".mp4", "video/mp4"],
+  [".png", "image/png"],
+  [".wav", "audio/wav"],
+  [".webp", "image/webp"],
+]);
+
+// 입력 파일 경로에 허용되는 확장자 — 프롬프트 인젝션으로 임의 파일(.env/.ssh/키)을
+// 서버에 업로드하는 exfil 경로를 막는다. 카테고리별로 분리해 잘못된 종류도 거른다.
+export const ALLOWED_IMAGE_EXTS = new Set([".jpg", ".jpeg", ".png", ".webp"]);
+export const ALLOWED_AUDIO_EXTS = new Set([".mp3", ".wav"]);
+export const ALLOWED_VIDEO_EXTS = new Set([".mp4"]);
+
+// data: URL 변환 상한(원본 바이트) — 서버 JSON 바디 상한 25MB 를 base64 팽창(4/3) 후에도
+// 넘지 않도록 잡는다. 25MB * 3/4 ≈ 18.75MB 에서 바디 여유분을 빼 17MB.
+export const MAX_DATA_URL_SOURCE_BYTES = 17 * 1024 * 1024;
+// 서버 readJsonBody 의 하드 상한. 요청 전체(여러 파일 합산) 인코딩 크기를 이 아래로 유지한다.
+export const SERVER_JSON_BODY_LIMIT_BYTES = 25 * 1024 * 1024;
+// 미디어 보존 기간 — render-job-store 와 동일하게 48시간.
+export const MEDIA_TTL_MS = 48 * 60 * 60 * 1000;
+
+export function mediaDir(stateDir) {
+  return path.join(stateDir, "media");
+}
+
+// base64 data: URL 의 인코딩 후 바이트 수 (헤더 포함 근사).
+export function encodedDataUrlBytes(sourceBytes, mimeType = "application/octet-stream") {
+  return `data:${mimeType};base64,`.length + Math.ceil(Number(sourceBytes || 0) / 3) * 4;
+}
+
+// 입력 경로 검증 — 확장자 화이트리스트 + 존재 + 상한. 위반 시 한국어 예외.
+export function assertAllowedInputFile(filePath, allowedExts, { kind = "파일" } = {}) {
+  const resolved = String(filePath || "").trim();
+  if (!resolved) throw new Error(`${kind} 경로가 비어 있습니다.`);
+  const ext = path.extname(resolved).toLowerCase();
+  if (!allowedExts.has(ext)) {
+    throw new Error(`허용되지 않은 ${kind} 확장자입니다: ${ext || "(없음)"} — 허용: ${[...allowedExts].join(", ")}`);
+  }
+  if (!existsSync(resolved)) throw new Error(`${kind}을(를) 찾을 수 없습니다: ${resolved}`);
+  const stats = statSync(resolved);
+  if (!stats.isFile()) throw new Error(`${kind}이(가) 일반 파일이 아닙니다: ${resolved}`);
+  if (stats.size > MAX_DATA_URL_SOURCE_BYTES) {
+    throw new Error(
+      `${kind}이(가) 너무 큽니다 (${Math.round(stats.size / 1024 / 1024)}MB > ${Math.round(MAX_DATA_URL_SOURCE_BYTES / 1024 / 1024)}MB): ${resolved}`,
+    );
+  }
+  return { ext, size: stats.size };
+}
+
+export function saveMediaBuffer(stateDir, name, buffer, { contentType = "" } = {}) {
+  const dir = mediaDir(stateDir);
+  mkdirSync(dir, { recursive: true });
+  const safeName = sanitizeOutputFilename(name, "media");
+  // 동일 밀리초 병렬 저장의 덮어쓰기 방지 — uuid 접미 + wx(존재 시 throw).
+  const filePath = path.join(dir, `${Date.now()}-${randomUUID().slice(0, 8)}-${safeName}`);
+  writeFileSync(filePath, buffer, { flag: "wx", mode: 0o600 });
+  return { bytes: buffer.length, contentType, filePath };
+}
+
+export function guessMimeType(filePath, fallback = "application/octet-stream") {
+  return MIME_BY_EXT.get(path.extname(String(filePath || "")).toLowerCase()) || fallback;
+}
+
+// 파일 → data: URL. 스티치 요청의 ttsAudioUrl/bgmAudioUrl 형식. 오디오 확장자만 허용.
+export function fileToDataUrl(filePath, { mimeType = "", allowedExts = ALLOWED_AUDIO_EXTS, kind = "오디오" } = {}) {
+  assertAllowedInputFile(filePath, allowedExts, { kind });
+  const mime = mimeType || guessMimeType(filePath);
+  return `data:${mime};base64,${readFileSync(filePath).toString("base64")}`;
+}
+
+// 파일 → {name, mimeType, base64} — commerce plan 의 productImages / 씬 참조 이미지 형식.
+export function fileToImagePayload(filePath) {
+  assertAllowedInputFile(filePath, ALLOWED_IMAGE_EXTS, { kind: "이미지" });
+  return {
+    base64: readFileSync(filePath).toString("base64"),
+    mimeType: guessMimeType(filePath, "image/jpeg"),
+    name: path.basename(filePath),
+  };
+}
+
+// 스티치 매니페스트 핸들 — JSON 저장 후 경로 반환, render_start 가 경로로 읽는다.
+export function savePayloadHandle(stateDir, payload, label = "stitch") {
+  return saveMediaBuffer(
+    stateDir,
+    `${label}-payload.json`,
+    Buffer.from(JSON.stringify(payload), "utf8"),
+    { contentType: "application/json" },
+  );
+}
+
+// render_start 가 넘겨받은 핸들만 읽도록 stateDir/media 안으로 제한한다.
+export function readPayloadHandle(filePath, { stateDir = "" } = {}) {
+  if (stateDir) {
+    const resolved = path.resolve(String(filePath || ""));
+    const base = path.resolve(mediaDir(stateDir));
+    if (resolved !== base && !resolved.startsWith(base + path.sep)) {
+      throw new Error("payloadPath는 stitch_timeline이 반환한 경로여야 합니다.");
+    }
+  }
+  return JSON.parse(readFileSync(filePath, "utf8"));
+}
+
+// 보존 기간이 지난 스테이징 미디어 정리 — 숨김 디렉터리에 GB 단위로 쌓이는 것 방지.
+export function pruneOldMedia(stateDir, { now = Date.now() } = {}) {
+  const dir = mediaDir(stateDir);
+  let removed = 0;
+  try {
+    for (const entry of readdirSync(dir)) {
+      const filePath = path.join(dir, entry);
+      try {
+        if (now - statSync(filePath).mtimeMs > MEDIA_TTL_MS) {
+          rmSync(filePath, { force: true });
+          removed += 1;
+        }
+      } catch {
+        // 개별 파일 오류는 무시
+      }
+    }
+  } catch {
+    // media 디렉터리 없음 등 — 무시
+  }
+  return removed;
+}