ima2-gen 1.1.0 → 1.1.2

package/lib/cardNewsManifestStore.js

@@ -0,0 +1,112 @@
+import { mkdir, readFile, readdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+
+export async function writeCardNewsManifest(generatedDir, manifest) {
+  const dir = join(generatedDir, "cardnews", manifest.setId);
+  await mkdir(dir, { recursive: true });
+  await writeFile(join(dir, "manifest.json"), JSON.stringify(manifest, null, 2));
+  return { dir, manifestFilename: "manifest.json" };
+}
+
+export async function writeCardSidecar(dir, filename, sidecar) {
+  await writeFile(join(dir, filename), JSON.stringify(sidecar, null, 2));
+}
+
+function cardUrl(setId, imageFilename) {
+  if (!imageFilename) return undefined;
+  return `/generated/cardnews/${encodeURIComponent(setId)}/${encodeURIComponent(imageFilename)}`;
+}
+
+function assertSafeSetId(setId) {
+  if (typeof setId === "string" && /^[a-zA-Z0-9_-]{3,120}$/.test(setId)) return setId;
+  const err = new Error("Card News set not found");
+  err.status = 404;
+  err.code = "CARD_NEWS_SET_NOT_FOUND";
+  throw err;
+}
+
+function manifestToPlan(manifest) {
+  return {
+    setId: manifest.setId,
+    title: manifest.title || "Untitled card news",
+    topic: manifest.topic || manifest.title || "Untitled card news",
+    imageTemplateId: manifest.imageTemplateId || "academy-lesson-square",
+    roleTemplateId: manifest.roleTemplateId || "mid-5",
+    size: manifest.size || "2048x2048",
+    generationStrategy: manifest.generationStrategy || "parallel-template-i2i",
+    cards: (manifest.cards || []).map((card, index) => ({
+      id: card.cardId || card.id || `card_${index + 1}`,
+      order: card.cardOrder || card.order || index + 1,
+      role: card.role || "card",
+      headline: card.headline || "",
+      body: card.body || "",
+      visualPrompt: card.visualPrompt || "",
+      textFields: Array.isArray(card.textFields) ? card.textFields : [],
+      references: card.references || [],
+      locked: !!card.locked,
+      status: card.status || "generated",
+      error: card.error?.message || card.error || undefined,
+      imageFilename: card.imageFilename || undefined,
+      url: card.url || cardUrl(manifest.setId, card.imageFilename),
+    })),
+  };
+}
+
+export async function readCardNewsSetPlan(ctx, setId) {
+  return manifestToPlan(await readCardNewsManifest(ctx, setId));
+}
+
+export async function readCardNewsManifest(ctx, setId) {
+  const safeSetId = assertSafeSetId(setId);
+  try {
+    const raw = await readFile(
+      join(ctx.config.storage.generatedDir, "cardnews", safeSetId, "manifest.json"),
+      "utf8",
+    );
+    return JSON.parse(raw);
+  } catch (err) {
+    if (err.code === "CARD_NEWS_SET_NOT_FOUND") throw err;
+    const notFound = new Error("Card News set not found");
+    notFound.status = 404;
+    notFound.code = "CARD_NEWS_SET_NOT_FOUND";
+    throw notFound;
+  }
+}
+
+export async function listCardNewsSets(ctx) {
+  const root = join(ctx.config.storage.generatedDir, "cardnews");
+  const entries = await readdir(root, { withFileTypes: true }).catch(() => []);
+  const sets = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    try {
+      const raw = await readFile(join(root, entry.name, "manifest.json"), "utf8");
+      const manifest = JSON.parse(raw);
+      const first = (manifest.cards || []).find((card) => card.imageFilename);
+      sets.push({
+        setId: manifest.setId || entry.name,
+        title: manifest.title || "Untitled card news",
+        cardCount: manifest.cardCount || manifest.cards?.length || 0,
+        createdAt: manifest.createdAt || 0,
+        sessionId: manifest.sessionId || null,
+        manifestUrl: `/api/cardnews/sets/${encodeURIComponent(manifest.setId || entry.name)}/manifest`,
+        folderLabel: `generated/cardnews/${manifest.setId || entry.name}`,
+        url: cardUrl(manifest.setId || entry.name, first?.imageFilename),
+        cards: (manifest.cards || []).map((card) => ({
+          id: card.cardId,
+          order: card.cardOrder,
+          headline: card.headline,
+          body: card.body,
+          textFields: Array.isArray(card.textFields) ? card.textFields : [],
+          imageFilename: card.imageFilename,
+          status: card.status || "generated",
+          url: cardUrl(manifest.setId || entry.name, card.imageFilename),
+        })),
+      });
+    } catch (err) {
+      console.warn("[card-news] set manifest read failed", entry.name, err.message);
+    }
+  }
+  sets.sort((a, b) => (b.createdAt || 0) - (a.createdAt || 0));
+  return sets;
+}

package/lib/cardNewsPlanner.js

@@ -0,0 +1,180 @@
+import { ulid } from "ulid";
+import { getRoleTemplate } from "./cardNewsRoleTemplateStore.js";
+import { getImageTemplate } from "./cardNewsTemplateStore.js";
+import { buildCardNewsPlannerMessages } from "./cardNewsPlannerPrompt.js";
+import { requestCardNewsPlannerJson } from "./cardNewsPlannerClient.js";
+import { repairPlannerOutput, validatePlannerOutput } from "./cardNewsPlannerSchema.js";
+import { waitForOAuthReady } from "./oauthProxy.js";
+
+function compactText(value, fallback) {
+  const text = typeof value === "string" ? value.trim() : "";
+  return text || fallback;
+}
+
+function detectBriefLanguage(input) {
+  const text = [input.topic, input.audience, input.goal, input.contentBrief].filter(Boolean).join(" ");
+  if (/[가-힣]/.test(text)) return "ko";
+  if (/[A-Za-z]/.test(text)) return "en";
+  return "und";
+}
+
+function fallbackLabel(role, lang) {
+  const ko = {
+    cta: "다음 행동",
+    problem: "왜 중요한가",
+    insight: "핵심 인사이트",
+    example: "예시로 보기",
+    data: "숫자로 확인",
+    summary: "요약",
+  };
+  const en = {
+    cta: "Next action",
+    problem: "Why it matters",
+    insight: "Key insight",
+    example: "Example",
+    data: "By the numbers",
+    summary: "Summary",
+  };
+  if (lang === "ko") return ko[role] || role;
+  if (lang === "en") return en[role] || role;
+  return "";
+}
+
+function headlineFor(role, topic, lang) {
+  const label = compactText(topic, "Card news");
+  if (role === "cover" || role === "hook") return label;
+  return fallbackLabel(role, lang) || label;
+}
+
+function bodyFor(role, brief, lang) {
+  const content = compactText(brief.content, "");
+  if (content) return content;
+  const target = compactText(brief.audience, lang === "ko" ? "독자" : "reader");
+  const goal = compactText(brief.goal, lang === "ko" ? "핵심 메시지" : "the key message");
+  if (lang === "ko") {
+    if (role === "cta") return `${target}가 바로 실행할 수 있는 다음 단계를 제안합니다.`;
+    if (role === "problem") return `${target}가 겪는 문제를 짧고 분명하게 보여줍니다.`;
+    if (role === "insight") return `${goal}을 이해하기 쉬운 한 문장으로 정리합니다.`;
+    return `${goal}을 카드 역할에 맞춰 전달합니다.`;
+  }
+  if (role === "cta") return `Suggest a next step ${target} can take immediately.`;
+  if (role === "problem") return `Show the problem ${target} faces in a concise way.`;
+  if (role === "insight") return `Explain ${goal} in one clear sentence.`;
+  return `Present ${goal} for this card.`;
+}
+
+function normalizeTextFields(fields) {
+  return Array.isArray(fields) ? fields : [];
+}
+
+function toCardNewsPlan(plannerOutput, input, roleTemplate) {
+  const topic = compactText(plannerOutput.topic, compactText(input.topic, input.title || "Untitled card news"));
+  return {
+    setId: input.setId || `cs_${ulid()}`,
+    title: compactText(plannerOutput.title, topic),
+    topic,
+    imageTemplateId: input.imageTemplateId || "academy-lesson-square",
+    roleTemplateId: roleTemplate.id,
+    size: input.size || "2048x2048",
+    generationStrategy: "parallel-template-i2i",
+    cards: plannerOutput.cards.map((card, index) => ({
+      id: `card_${index + 1}`,
+      order: index + 1,
+      role: card.role,
+      headline: card.headline,
+      body: card.body,
+      visualPrompt: card.visualPrompt,
+      textFields: normalizeTextFields(card.textFields),
+      templateSlotAssignments: {
+        title: "headline",
+        body: "body",
+        image: "visual",
+      },
+      references: card.references || [],
+      locked: false,
+      status: "draft",
+    })),
+  };
+}
+
+export function createDeterministicCardNewsDraft(input = {}) {
+  const roleTemplate = getRoleTemplate(input.roleTemplateId);
+  const topic = compactText(input.topic, input.title || "Untitled card news");
+  const title = compactText(input.title, topic);
+  const brief = {
+    audience: input.audience,
+    goal: input.goal,
+    content: input.contentBrief,
+  };
+  const lang = detectBriefLanguage(input);
+  const output = {
+    title,
+    topic,
+    audience: compactText(input.audience, ""),
+    goal: compactText(input.goal, ""),
+    cards: roleTemplate.roles.map((role, idx) => ({
+      order: idx + 1,
+      role: role.role,
+      headline: headlineFor(role.role, topic, lang),
+      body: bodyFor(role.role, brief, lang),
+      visualPrompt: `${role.promptHint}, ${topic}`,
+      textFields: [],
+      references: [],
+      locked: false,
+    })),
+  };
+  return toCardNewsPlan(output, input, roleTemplate);
+}
+
+function plannerError(message, code, status) {
+  const err = new Error(message);
+  err.code = code;
+  err.status = status;
+  return err;
+}
+
+export async function createCardNewsDraft(ctxOrInput = {}, maybeInput = {}) {
+  const hasCtx = !!ctxOrInput?.config;
+  const ctx = hasCtx ? ctxOrInput : null;
+  const input = hasCtx ? maybeInput : ctxOrInput;
+  const roleTemplate = getRoleTemplate(input.roleTemplateId);
+
+  if (!ctx) return createDeterministicCardNewsDraft(input);
+  if (!ctx.config.cardNewsPlanner?.enabled) {
+    return {
+      plan: createDeterministicCardNewsDraft(input),
+      planner: { mode: "deterministic-fallback", model: "none", repaired: false },
+    };
+  }
+
+  const imageTemplate = await getImageTemplate(ctx, input.imageTemplateId || "academy-lesson-square");
+  try {
+    await waitForOAuthReady(ctx);
+    const messages = buildCardNewsPlannerMessages({ ...input, roleTemplate, imageTemplate });
+    const raw = await requestCardNewsPlannerJson({ messages }, {
+      oauthUrl: ctx.oauthUrl,
+      model: ctx.config.cardNewsPlanner.model,
+      timeoutMs: ctx.config.cardNewsPlanner.timeoutMs,
+    });
+    let result = validatePlannerOutput(raw.output, roleTemplate);
+    if (!result.ok) result = repairPlannerOutput(raw.output, { ...input, roleTemplate });
+    if (!result.ok) throw plannerError("Planner schema invalid", "PLANNER_SCHEMA_INVALID", 422);
+    return {
+      plan: toCardNewsPlan(result.plan, input, roleTemplate),
+      planner: { mode: raw.mode, model: raw.model, repaired: result.repaired },
+    };
+  } catch (err) {
+    if (ctx.config.cardNewsPlanner.deterministicFallback) {
+      return {
+        plan: createDeterministicCardNewsDraft(input),
+        planner: {
+          mode: "deterministic-fallback",
+          model: ctx.config.cardNewsPlanner.model,
+          repaired: true,
+        },
+      };
+    }
+    if (err.code) throw err;
+    throw plannerError(err.message || "Planner unavailable", "PLANNER_UNAVAILABLE", 503);
+  }
+}

package/lib/cardNewsPlannerClient.js

@@ -0,0 +1,112 @@
+import { config } from "../config.js";
+import { CARD_NEWS_PLANNER_SCHEMA } from "./cardNewsPlannerSchema.js";
+import { logEvent } from "./logger.js";
+
+function plannerError(message, code, status = 502) {
+  const err = new Error(message);
+  err.code = code;
+  err.status = status;
+  return err;
+}
+
+function extractText(json) {
+  if (typeof json.output_text === "string") return json.output_text;
+  for (const item of json.output || []) {
+    for (const content of item.content || []) {
+      if (typeof content.text === "string") return content.text;
+      if (typeof content.value === "string") return content.value;
+    }
+  }
+  return "";
+}
+
+async function requestJson({ oauthUrl, model, messages, timeoutMs, structured }) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const body = {
+      model,
+      input: messages,
+      stream: false,
+      ...(structured
+        ? {
+            text: {
+              format: {
+                type: "json_schema",
+                name: "card_news_planner_output",
+                strict: true,
+                schema: CARD_NEWS_PLANNER_SCHEMA,
+              },
+            },
+          }
+        : { text: { format: { type: "json_object" } } }),
+    };
+    const res = await fetch(`${oauthUrl}/v1/responses`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      signal: controller.signal,
+      body: JSON.stringify(body),
+    });
+    logEvent("card-news-planner", "response", { model, status: res.status, structured });
+    if (!res.ok) {
+      const text = await res.text();
+      const err = plannerError("Planner upstream failed", "PLANNER_UPSTREAM_FAILED", 502);
+      err.upstreamStatus = res.status;
+      err.upstreamBodyChars = text.length;
+      throw err;
+    }
+    const json = await res.json();
+    return extractText(json);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+async function requestChatJson({ oauthUrl, model, messages, timeoutMs }) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const res = await fetch(`${oauthUrl}/v1/chat/completions`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      signal: controller.signal,
+      body: JSON.stringify({
+        model,
+        messages,
+        response_format: { type: "json_object" },
+      }),
+    });
+    logEvent("card-news-planner", "chat_response", { model, status: res.status });
+    if (!res.ok) {
+      const text = await res.text();
+      const err = plannerError("Planner upstream failed", "PLANNER_UPSTREAM_FAILED", 502);
+      err.upstreamStatus = res.status;
+      err.upstreamBodyChars = text.length;
+      throw err;
+    }
+    const json = await res.json();
+    return json.choices?.[0]?.message?.content || "";
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+export async function requestCardNewsPlannerJson(input, options = {}) {
+  const oauthUrl = options.oauthUrl || `http://127.0.0.1:${config.oauth.proxyPort}`;
+  const model = options.model || config.cardNewsPlanner.model;
+  const timeoutMs = options.timeoutMs || config.cardNewsPlanner.timeoutMs;
+  let text = "";
+  let mode = "structured-output";
+  try {
+    text = await requestJson({ oauthUrl, model, messages: input.messages, timeoutMs, structured: true });
+  } catch (err) {
+    if (err.code !== "PLANNER_UPSTREAM_FAILED") throw err;
+    mode = "json-mode";
+    text = await requestChatJson({ oauthUrl, model, messages: input.messages, timeoutMs });
+  }
+  try {
+    return { output: JSON.parse(text), mode, model };
+  } catch {
+    throw plannerError("Planner returned invalid JSON", "PLANNER_INVALID_JSON", 502);
+  }
+}

package/lib/cardNewsPlannerPrompt.js

@@ -0,0 +1,60 @@
+export function buildCardNewsPlannerMessages(input = {}) {
+  const roleTemplate = input.roleTemplate || {};
+  const imageTemplate = input.imageTemplate || {};
+  return [
+    {
+      role: "developer",
+      content: [
+        "You are a Card News planning assistant.",
+        "Return JSON only. Do not call image tools. Do not generate images.",
+        "Keep the selected card count and role order exactly.",
+        "Preserve the user's original language for headline, body, textFields, and visualPrompt.",
+        "Do not translate to English unless explicitly requested.",
+        "If the user mixes languages, preserve the mix.",
+        "If the user provides exact text, preserve it exactly.",
+        "Role names such as cover/problem/cta are structural labels, not visible design text.",
+        "Keep headline and body as UI/manifest text.",
+        "Only textFields[].text with renderMode=\"in-image\" is intended to appear inside the image.",
+        "Create textFields only for text that should be readable inside the image.",
+        "Prefer template slot ids and placements when assigning textFields.",
+        "Use headline textFields for hook/cover cards, body or caption textFields for explanation cards, and cta textFields only for action cards.",
+        "Never put structural role labels such as CTA, cover, problem, insight, or example into textFields unless the user explicitly requested that exact visible wording.",
+        "Placement examples: top-right badge, top-center headline, center-left supporting caption, bottom-center CTA.",
+        "Make visualPrompt describe scene, layout, style, spatial composition, and text-box placement only.",
+        "Do not duplicate visible text in visualPrompt except to reference a text box position.",
+        "visualPrompt may mention a text box location, but the exact readable copy must live only in textFields[].text.",
+      ].join("\n"),
+    },
+    {
+      role: "user",
+      content: JSON.stringify({
+        topic: input.topic || "",
+        audience: input.audience || "",
+        goal: input.goal || "",
+        contentBrief: input.contentBrief || "",
+        size: input.size || "2048x2048",
+        imageTemplate: {
+          id: imageTemplate.id,
+          name: imageTemplate.name,
+          stylePrompt: imageTemplate.stylePrompt,
+          recommendedOutputSizes: imageTemplate.recommendedOutputSizes || [],
+          slots: imageTemplate.slots || [],
+          palette: imageTemplate.palette || [],
+        },
+        roleTemplate: {
+          id: roleTemplate.id,
+          roles: (roleTemplate.roles || []).map((role) => ({
+            role: role.role,
+            promptHint: role.promptHint,
+            preferredSlots: role.preferredSlots || [],
+          })),
+        },
+        textFieldPolicy: {
+          visibleTextSource: "textFields[].text",
+          renderableMode: "in-image",
+          structuralRoleLabelsAreNotVisibleText: true,
+        },
+      }),
+    },
+  ];
+}