ima2-gen 1.1.0 → 1.1.2

package/docs/FAQ.md

@@ -0,0 +1,256 @@
+# ima2-gen FAQ
+
+Last reviewed: 2026-04-25
+
+This FAQ collects the questions that tend to come up after installing or updating `ima2-gen`. The README stays short; this page is the place for practical details and recovery steps.
+
+For Korean, see [FAQ.ko.md](FAQ.ko.md).
+
+## Quick fixes
+
+| Symptom | Try first |
+|---|---|
+| The server is unreachable | Run `ima2 serve`, then `ima2 ping`. |
+| OAuth login fails | Run `npx @openai/codex login`, then restart `ima2 serve`. |
+| API key generation is disabled | Use OAuth for image generation. API keys are only used by auxiliary paths. |
+| Old gallery images look missing | Run `ima2 doctor`, then see [Recover Old Generated Images](RECOVER_OLD_IMAGES.md). |
+| `gpt-5.5` fails | Update Codex CLI first, then try `gpt-5.4` as the stable fallback. |
+| Reference upload fails | Use JPEG/PNG, lower the resolution, and keep references to 5 images or fewer. |
+| Windows reports OAuth/proxy failures around port `10531` | Run `ima2 doctor`; if needed start with `IMA2_OAUTH_PROXY_PORT=11531 ima2 serve`. |
+
+## Install and update
+
+### What version of Node do I need?
+
+Use Node.js 20 or newer. The package declares Node `>=20`, and the README badge follows that requirement.
+
+### Should I use `npx` or a global install?
+
+Both are supported.
+
+```bash
+npx ima2-gen serve
+```
+
+or:
+
+```bash
+npm install -g ima2-gen
+ima2 serve
+```
+
+If an old global install behaves strangely, update first:
+
+```bash
+npm install -g ima2-gen@latest
+```
+
+Then run:
+
+```bash
+ima2 doctor
+```
+
+### Windows says `spawn EINVAL`. What should I do?
+
+Update to the latest version. Older versions had trouble spawning npm/npx shims on Windows. Current builds route those commands through a Windows-safe path.
+
+If Codex login itself is unreliable on native Windows, WSL can be the more predictable environment.
+
+### Windows says `EBUSY` or `resource busy or locked` during update. What should I do?
+
+This usually means npm cannot replace the global package because a running
+`ima2 serve`, stale `node.exe`, terminal, Explorer window, antivirus, or indexer
+still holds the package folder. Stop ima2, close related terminals, end stale
+`node.exe` processes if needed, then retry:
+
+```bash
+npm install -g ima2-gen@latest
+```
+
+If the lock persists, reboot Windows and run the update before starting ima2
+again.
+
+## Authentication and providers
+
+### Do I need an OpenAI API key?
+
+No for image generation. The normal generation path uses your local Codex/ChatGPT OAuth session.
+
+You may still see an API key detected in settings. That only means an API key exists in env/config. Image generation routes still reject `provider: "api"` with `APIKEY_DISABLED`.
+
+### Why does the settings page say "Configured but disabled"?
+
+It means `ima2-gen` found an API key, but API-key image generation is intentionally disabled in this build. Use OAuth for generation.
+
+### If Codex CLI is already logged in, does ima2-gen reuse it?
+
+Yes. `ima2-gen` checks for an existing Codex login and uses the local OAuth path. If detection fails or the token expires, run:
+
+```bash
+npx @openai/codex login
+ima2 doctor
+```
+
+Then restart `ima2 serve`.
+
+### What if I see `Provided authentication token is expired`?
+
+Your Codex/ChatGPT OAuth session needs to be refreshed.
+
+```bash
+npx @openai/codex login
+ima2 serve
+```
+
+If this happens on a company network, a firewall, VPN, proxy, or captive portal may also be blocking the OAuth flow.
+
+## Models and quota
+
+### Which model should I use?
+
+Start with `gpt-5.4` for the safest balanced workflow.
+
+- `gpt-5.4`: recommended balanced choice.
+- `gpt-5.4-mini`: current app default and faster draft model.
+- `gpt-5.5`: strongest quality option when supported.
+
+### Why does `gpt-5.5` fail when other models work?
+
+`gpt-5.5` may require a newer Codex CLI, backend capability, or account/quota availability. Update Codex CLI first. If it still fails, use `gpt-5.4` as the stable fallback.
+
+### How many images can Plus or Pro generate?
+
+Do not treat any community number as a guarantee. OAuth generation can be limited by account, backend capability, traffic, and policy changes. `ima2-gen` does not publish a fixed Plus/Pro image count because that number is not stable enough to document as a promise.
+
+## Gallery and generated files
+
+### Where are generated images stored?
+
+Current versions store generated images in your user data folder:
+
+```text
+macOS / Linux: ~/.ima2/generated
+Windows: %USERPROFILE%\.ima2\generated
+```
+
+You can override that with `IMA2_GENERATED_DIR`.
+
+### Why did old gallery images look missing after an update?
+
+Older versions stored generated images inside the installed package folder. Recent versions moved the gallery to user data storage so package updates do not mix app code with runtime files.
+
+Sorry for the scare. If the old global install folder was replaced during an update, the previous `generated/` folder may no longer be on disk. `ima2-gen` can recover old files only when that old folder still exists.
+
+Run:
+
+```bash
+ima2 doctor
+```
+
+Then follow [Recover Old Generated Images](RECOVER_OLD_IMAGES.md).
+
+### Does ima2-gen delete my old images during this migration?
+
+No. The migration is copy-only. It does not delete or move legacy folders. If old files are not found, the likely issue is that the old global install folder is no longer present on disk.
+
+### What does "Open folder" open?
+
+The gallery's **Open folder** button opens the generated image folder on the machine running `ima2 serve`.
+
+That is usually your own computer. If you are using a remote server, SSH session, VM, container, WSL, or another machine on your network, the folder opens or resolves on that server machine, not necessarily on the browser device.
+
+### Is Card News part of the stable public release?
+
+Not yet. Card News is still dev-only and experimental. The default published
+runtime should keep it hidden unless it is explicitly enabled for development,
+and public docs should not treat it as a stable feature.
+
+## Reference images
+
+### How many reference images can I attach?
+
+Up to 5.
+
+### What formats work best?
+
+Use JPEG or PNG. The browser path does not support HEIC/HEIF directly, so convert those images before attaching them.
+
+### What if a reference image is too large?
+
+The app compresses large JPEG/PNG files before upload. If a file still fails, lower the resolution or convert it to JPEG/PNG and try again.
+
+The API may report reference errors such as `REF_TOO_MANY`, `REF_TOO_LARGE`, `REF_NOT_BASE64`, or `REF_EMPTY`.
+
+## Network and OAuth errors
+
+### Why did the backend or OAuth proxy move to another port?
+
+`ima2-gen` is a local app. If the preferred backend port `3333` or OAuth proxy port `10531` is already in use, the runtime can fall back to the next available port and records the actual URLs in:
+
+```text
+~/.ima2/server.json
+```
+
+Use:
+
+```bash
+ima2 doctor
+```
+
+to see the configured and actual backend/OAuth URLs.
+
+### Windows: what if `AnySign4PC.exe` owns port `10531`?
+
+Some Windows security software can occupy the default OAuth proxy port. Current builds track the actual fallback port, but you can also force a quieter range:
+
+```bash
+IMA2_OAUTH_PROXY_PORT=11531 ima2 serve
+```
+
+For split frontend development, point Vite at the actual backend:
+
+```bash
+VITE_IMA2_API_TARGET=http://localhost:3334 npm run ui:dev
+```
+
+### What does `failed to fetch` mean?
+
+Usually one of these:
+
+- the local OAuth proxy is not ready,
+- the server was restarted,
+- a VPN/proxy/firewall blocked the request,
+- the network dropped while Codex/ChatGPT OAuth was being used.
+
+Try:
+
+```bash
+ima2 doctor
+ima2 ping
+```
+
+Then restart `ima2 serve` if needed.
+
+### What should I check on a company computer?
+
+OAuth may require access to OpenAI and ChatGPT/Codex-related hosts. A corporate firewall, TLS inspection, VPN, or proxy can break the flow. Try a different network if login and `failed to fetch` errors keep repeating.
+
+## CLI troubleshooting checklist
+
+Run these in order:
+
+```bash
+ima2 doctor
+ima2 status
+ima2 ping
+ima2 ps
+npx @openai/codex login
+npm install -g ima2-gen@latest
+```
+
+If you run the server on a non-default port:
+
+```bash
+IMA2_SERVER=http://localhost:3333 ima2 ping
+```

package/docs/README.ja.md

@@ -143,6 +143,8 @@ environment variables > ~/.ima2/config.json > built-in defaults
 
 Endpoint 一覧は [API Reference](API.md) に分離しました。
 
+詳しいFAQは [FAQ](FAQ.md) にまとめています。アップデート後に以前のギャラリー画像が見えない場合は、まず [Recover Old Generated Images](RECOVER_OLD_IMAGES.md) を確認してください。
+
 ## Troubleshooting
 
 **`ima2 ping` が server unreachable になる**
@@ -166,6 +168,8 @@ JPEG/PNG は送信前に自動圧縮されます。それでも失敗する場
 **Port が突然 `3457` になる**
 別のローカルツールから `PORT=3457` が引き継がれている可能性があります。`unset PORT` するか、`IMA2_PORT=3333 ima2 serve` で起動してください。
 
+より詳しい確認手順は [FAQ](FAQ.md) を参照してください。
+
 ## Development
 
 ```bash

package/docs/README.ko.md

@@ -98,7 +98,7 @@ Style sheet는 반복해서 쓰고 싶은 시각적 방향을 저장하는 기
 
 | 명령어 | 설명 |
 |---|---|
-| `ima2 serve` | 로컬 웹 서버 시작 |
+| `ima2 serve [--dev]` | 로컬 웹 서버 시작. `--dev`는 서버 진단 로그를 자세히 표시 |
 | `ima2 setup` | 인증 설정 다시 구성 |
 | `ima2 status` | config와 OAuth 상태 확인 |
 | `ima2 doctor` | Node, 패키지, config, auth 진단 |
@@ -136,13 +136,22 @@ environment variables > ~/.ima2/config.json > built-in defaults
 | `IMA2_CONFIG_DIR` | `~/.ima2` | config와 SQLite 저장 위치 |
 | `IMA2_GENERATED_DIR` | `~/.ima2/generated` | 생성 이미지 저장 위치 |
 | `IMA2_NO_OAUTH_PROXY` | — | `1`이면 OAuth 프록시 자동 시작 비활성화 |
+| `IMA2_LOG_LEVEL` | `warn` | 일반 `serve`는 `warn`, dev 모드는 `debug`. `debug`, `info`, `warn`, `error`, `silent` 지원 |
 | `IMA2_INFLIGHT_TERMINAL_TTL_MS` | `30000` | 디버그용 최근 작업 보존 시간 |
 | `OPENAI_API_KEY` | — | 보조 기능용 API 키. 이미지 생성용은 아님 |
 
+### 로그 모드
+
+`ima2 serve`는 일반 사용자 기준으로 터미널 출력을 조용하게 유지합니다. 시작 URL, 경고, 오류는 보이지만 요청/노드/OAuth structured log는 기본적으로 숨깁니다.
+
+요청 ID, 노드 생성 단계, OAuth stream 진단, inflight 상태 전환을 봐야 하면 `ima2 serve --dev`, `npm run dev`, 또는 `IMA2_LOG_LEVEL=debug ima2 serve`를 사용하세요. 명시한 `IMA2_LOG_LEVEL`과 `~/.ima2/config.json` 값은 기본값보다 우선합니다.
+
 ## API 문서
 
 엔드포인트 목록은 [API Reference](API.md)로 분리했습니다.
 
+자주 묻는 질문은 [FAQ](FAQ.ko.md)에 정리했습니다. 업데이트 후 예전 이미지가 안 보이면 [예전 이미지 복구 안내](RECOVER_OLD_IMAGES.md)를 먼저 확인하세요.
+
 ## 문제 해결
 
 **`ima2 ping`이 서버에 연결하지 못한다고 나와요**
@@ -166,6 +175,8 @@ JPEG/PNG는 업로드 전에 자동 압축됩니다. 그래도 실패하면 해
 **포트가 갑자기 `3457`로 떠요**
 다른 로컬 도구에서 `PORT=3457`이 상속됐을 수 있습니다. `unset PORT`를 실행하거나 `IMA2_PORT=3333 ima2 serve`로 시작하세요.
 
+더 자세한 답변은 [FAQ](FAQ.ko.md)를 확인하세요.
+
 ## 개발
 
 ```bash
@@ -177,6 +188,8 @@ npm test
 npm run build
 ```
 
+`npm run dev`는 UI를 빌드한 뒤 `server.js`를 `--watch`로 실행하고, 서버 진단 로그를 자세히 표시합니다.
+
 ## 라이선스
 
 MIT

package/docs/README.zh-CN.md

@@ -143,6 +143,8 @@ environment variables > ~/.ima2/config.json > built-in defaults
 
 接口列表已移到 [API Reference](API.md)。
 
+更详细的常见问题整理在 [FAQ](FAQ.md)。如果更新后看不到旧图库图片，请先查看[旧图片恢复指南](RECOVER_OLD_IMAGES.md)。
+
 ## 常见问题
 
 **`ima2 ping` 提示 server unreachable**
@@ -166,6 +168,8 @@ JPEG/PNG 会在上传前自动压缩。如果仍然失败，请转成更低分
 **端口突然变成 `3457`**
 shell 可能继承了其他本地工具的 `PORT=3457`。运行 `unset PORT`，或使用 `IMA2_PORT=3333 ima2 serve`。
 
+更多面向新手的排查步骤请查看 [FAQ](FAQ.md)。
+
 ## Development
 
 ```bash

package/docs/RECOVER_OLD_IMAGES.md

@@ -2,6 +2,8 @@
 
 `ima2-gen` moved generated images to a safer user-data folder in `v1.0.8`.
 
+For broader install and troubleshooting questions, see the [FAQ](FAQ.md) or [Korean FAQ](FAQ.ko.md).
+
 ## What changed
 
 Versions up to `v1.0.7` stored generated images inside the installed package:

package/lib/cardNewsGenerator.js

@@ -0,0 +1,162 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { ulid } from "ulid";
+import { generateViaOAuth } from "./oauthProxy.js";
+import { readTemplateBaseB64 } from "./cardNewsTemplateStore.js";
+import { writeCardNewsManifest, writeCardSidecar } from "./cardNewsManifestStore.js";
+
+function formatRenderedTextInstruction(textFields = []) {
+  const visible = (Array.isArray(textFields) ? textFields : [])
+    .filter((field) => field?.renderMode === "in-image" && field.text);
+  if (!visible.length) {
+    return [
+      "Do not render readable text unless explicitly listed.",
+      "Do not render role labels, schema keys, placeholder labels, or untranslated summaries.",
+    ].join("\n");
+  }
+  return [
+    "Render only the following readable text items exactly as written:",
+    ...visible.map((field) => {
+      const slot = field.slotId ? ` in slot ${field.slotId}` : "";
+      return `- ${field.kind} at ${field.placement}${slot}: "${field.text}"`;
+    }),
+    "Preserve the language and spelling of every listed text item.",
+    "Do not render role labels, schema keys, placeholder labels, or extra text.",
+  ].join("\n");
+}
+
+export function assemblePrompt(template, card) {
+  return [
+    template.stylePrompt,
+    card.visualPrompt,
+    formatRenderedTextInstruction(card.textFields),
+    template.negativePrompt ? `Avoid: ${template.negativePrompt}` : "",
+  ].filter(Boolean).join("\n");
+}
+
+async function mapLimit(items, limit, fn) {
+  const out = new Array(items.length);
+  let next = 0;
+  async function worker() {
+    while (next < items.length) {
+      const i = next++;
+      out[i] = await fn(items[i], i);
+    }
+  }
+  await Promise.all(Array.from({ length: Math.min(limit, items.length) }, worker));
+  return out;
+}
+
+export async function generateCardNewsSet(ctx, input, options = {}) {
+  const setId = input.setId || `cs_${ulid()}`;
+  const cards = Array.isArray(input.cards) ? input.cards : [];
+  const cardsToGenerate = cards.filter((card) => !card.locked);
+  if (cardsToGenerate.length === 0) {
+    const err = new Error("cards are required");
+    err.status = 400;
+    err.code = "CARD_NEWS_CARDS_REQUIRED";
+    throw err;
+  }
+
+  const imageTemplateId = input.imageTemplateId || "academy-lesson-square";
+  const { template, templateBase, b64: templateB64 } = await readTemplateBaseB64(ctx, imageTemplateId);
+  const dir = join(ctx.config.storage.generatedDir, "cardnews", setId);
+  await mkdir(dir, { recursive: true });
+
+  const quality = input.quality || "medium";
+  const size = input.size || template.size || "2048x2048";
+  const moderation = input.moderation || "low";
+  const model = input.model || ctx.config.imageModels.default;
+  const generateFn = options.generateFn || generateViaOAuth;
+
+  const generatedCards = await mapLimit(cardsToGenerate, Number(input.concurrency) || 2, async (card, index) => {
+    const cardOrder = Number(card.cardOrder || card.order || index + 1);
+    const baseFilename = `card-${String(cardOrder).padStart(2, "0")}`;
+    const imageFilename = `${baseFilename}.png`;
+    const sidecarFilename = `${baseFilename}.json`;
+    const requestId = input.requestId || `${setId}_${baseFilename}`;
+    const prompt = assemblePrompt(template, card);
+    let result = null;
+    let error = null;
+    if (typeof options.onCardStart === "function") {
+      await options.onCardStart({ ...card, cardOrder, cardId: card.id || `card_${cardOrder}` });
+    }
+    try {
+      result = await generateFn(
+        prompt,
+        quality,
+        size,
+        moderation,
+        [templateB64, ...(Array.isArray(card.references) ? card.references : [])],
+        requestId,
+        input.promptMode || "direct",
+        ctx,
+        { model },
+      );
+      if (!result?.b64) {
+        error = { code: "CARD_NEWS_EMPTY_IMAGE", message: "No image data returned" };
+      } else {
+        await writeFile(join(dir, imageFilename), Buffer.from(result.b64, "base64"));
+      }
+    } catch (err) {
+      error = { code: err.code || "CARD_NEWS_CARD_FAILED", message: err.message || "Card generation failed" };
+    }
+    const sidecar = {
+      kind: "card-news-card",
+      setId,
+      sessionId: input.sessionId || null,
+      requestId,
+      cardId: card.id || `card_${cardOrder}`,
+      cardOrder,
+      title: input.title || "Untitled card news",
+      role: card.role || "card",
+      headline: card.headline || "",
+      body: card.body || "",
+      textFields: Array.isArray(card.textFields) ? card.textFields : [],
+      imageTemplateId,
+      generationStrategy: "parallel-template-i2i",
+      templateBase,
+      prompt,
+      visualPrompt: card.visualPrompt || "",
+      imageFilename: error ? null : imageFilename,
+      sidecarFilename,
+      locked: !!card.locked,
+      status: error ? "error" : "generated",
+      error,
+      createdAt: Date.now(),
+      generatedAt: error ? null : Date.now(),
+      revisedPrompt: result?.revisedPrompt || null,
+    };
+    await writeCardSidecar(dir, sidecarFilename, sidecar);
+    if (typeof options.onCardDone === "function") await options.onCardDone(sidecar);
+    return sidecar;
+  });
+
+  const manifest = {
+    kind: "card-news-set",
+    setId,
+    sessionId: input.sessionId || null,
+    requestId: input.requestId || null,
+    title: input.title || "Untitled card news",
+    imageTemplateId,
+    roleTemplateId: input.roleTemplateId || "mid-5",
+    generationStrategy: "parallel-template-i2i",
+    size,
+    cardCount: generatedCards.length,
+    createdAt: Date.now(),
+    cards: generatedCards,
+  };
+  await writeCardNewsManifest(ctx.config.storage.generatedDir, manifest);
+  return {
+    setId,
+    manifest,
+    cards: generatedCards.map((card) => ({
+      ...card,
+      id: card.cardId,
+      order: card.cardOrder,
+      url: card.imageFilename
+        ? `/generated/cardnews/${encodeURIComponent(setId)}/${encodeURIComponent(card.imageFilename)}`
+        : undefined,
+    })),
+  };
+}

package/lib/cardNewsJobStore.js

@@ -0,0 +1,107 @@
+import { ulid } from "ulid";
+
+const jobs = new Map();
+const TTL_MS = 30 * 60 * 1000;
+
+function summarize(job) {
+  const generated = job.cards.filter((card) => card.status === "generated").length;
+  const errors = job.cards.filter((card) => card.status === "error").length;
+  return {
+    jobId: job.jobId,
+    setId: job.setId,
+    status: job.status,
+    total: job.cards.length,
+    generated,
+    errors,
+    cards: job.cards,
+    updatedAt: job.updatedAt,
+  };
+}
+
+function statusFromCards(cards) {
+  const active = cards.some((card) => card.status === "queued" || card.status === "generating");
+  if (active) return "running";
+  const errors = cards.some((card) => card.status === "error");
+  const generated = cards.some((card) => card.status === "generated");
+  if (errors && generated) return "partial";
+  if (errors) return "error";
+  return "done";
+}
+
+export function createCardNewsJob(plan) {
+  const now = Date.now();
+  const job = {
+    jobId: `cj_${ulid()}`,
+    setId: plan.setId,
+    status: "queued",
+    plan,
+    cards: (plan.cards || []).map((card) => ({
+      id: card.id,
+      order: card.order,
+      status: card.locked ? "skipped" : "queued",
+      textFields: Array.isArray(card.textFields) ? card.textFields : [],
+    })),
+    createdAt: now,
+    updatedAt: now,
+  };
+  jobs.set(job.jobId, job);
+  return summarize(job);
+}
+
+export function getCardNewsJob(jobId) {
+  const job = jobs.get(jobId);
+  if (!job) return null;
+  return summarize(job);
+}
+
+export function updateCardNewsJob(jobId, patch) {
+  const job = jobs.get(jobId);
+  if (!job) return null;
+  Object.assign(job, patch, { updatedAt: Date.now() });
+  return summarize(job);
+}
+
+export function updateCardNewsJobCard(jobId, cardId, patch) {
+  const job = jobs.get(jobId);
+  if (!job) return null;
+  job.cards = job.cards.map((card) => (
+    card.id === cardId ? {
+      ...card,
+      ...patch,
+      textFields: Array.isArray(patch.textFields) ? patch.textFields : card.textFields,
+    } : card
+  ));
+  job.status = statusFromCards(job.cards);
+  job.updatedAt = Date.now();
+  return summarize(job);
+}
+
+export function finishCardNewsJob(jobId) {
+  const job = jobs.get(jobId);
+  if (!job) return null;
+  job.status = statusFromCards(job.cards);
+  job.updatedAt = Date.now();
+  return summarize(job);
+}
+
+export function getCardNewsJobPlan(jobId) {
+  return jobs.get(jobId)?.plan || null;
+}
+
+export function retryCardNewsJob(jobId, cardIds) {
+  const job = jobs.get(jobId);
+  if (!job) return null;
+  const wanted = new Set(cardIds || []);
+  job.cards = job.cards.map((card) => (
+    wanted.has(card.id) && card.status === "error" ? { ...card, status: "queued", error: undefined } : card
+  ));
+  job.status = "queued";
+  job.updatedAt = Date.now();
+  return summarize(job);
+}
+
+export function reapCardNewsJobs(now = Date.now()) {
+  for (const [jobId, job] of jobs.entries()) {
+    if (now - job.updatedAt > TTL_MS) jobs.delete(jobId);
+  }
+}