ima2-gen 1.1.0 → 1.1.2

package/lib/requestLogger.js

@@ -0,0 +1,48 @@
+import { randomUUID } from "crypto";
+import { logEvent } from "./logger.js";
+
+const REQUEST_ID_RE = /^[A-Za-z0-9._:-]{1,128}$/;
+const IGNORED_LOG_PATHS = new Set(["/api/health", "/api/inflight"]);
+
+export function normalizeRequestId(value) {
+  return typeof value === "string" && REQUEST_ID_RE.test(value) ? value : `req_${randomUUID()}`;
+}
+
+function requestPath(req) {
+  return String(req.originalUrl || req.url || "").split("?")[0] || "/";
+}
+
+export function createRequestLogger() {
+  return function requestLogger(req, res, next) {
+    const path = requestPath(req);
+    if (!path.startsWith("/api/")) return next();
+
+    const requestId = normalizeRequestId(req.get("x-request-id"));
+    const startedAt = Date.now();
+    req.id = requestId;
+    res.setHeader("X-Request-Id", requestId);
+
+    const ignoreLog = IGNORED_LOG_PATHS.has(path);
+    if (!ignoreLog) {
+      logEvent("http", "request", {
+        requestId,
+        method: req.method,
+        path,
+        client: req.get("x-ima2-client") || "ui",
+      });
+    }
+
+    res.on("finish", () => {
+      if (ignoreLog) return;
+      logEvent("http", "response", {
+        requestId,
+        method: req.method,
+        path,
+        status: res.statusCode,
+        durationMs: Date.now() - startedAt,
+      });
+    });
+
+    next();
+  };
+}

package/lib/runtimePorts.js

@@ -0,0 +1,93 @@
+import { createServer } from "node:net";
+
+const DEFAULT_MAX_ATTEMPTS = 20;
+
+export function parseLocalhostPortFromUrl(url) {
+  try {
+    const parsed = new URL(url);
+    const port = Number(parsed.port);
+    return Number.isFinite(port) && port > 0 ? port : null;
+  } catch {
+    return null;
+  }
+}
+
+export function stripV1FromOAuthUrl(url) {
+  return String(url || "").replace(/\/v1\/?$/, "");
+}
+
+export function parseOAuthReadyUrl(line) {
+  const text = String(line || "");
+  const match = text.match(/https?:\/\/(?:127\.0\.0\.1|localhost):\d+(?:\/v1)?/i);
+  return match ? stripV1FromOAuthUrl(match[0]) : null;
+}
+
+function checkPort(port, host) {
+  return new Promise((resolve, reject) => {
+    const probe = createServer()
+      .once("error", (err) => {
+        probe.close(() => {});
+        reject(err);
+      })
+      .once("listening", () => {
+        probe.close(() => resolve(true));
+      });
+    if (host) probe.listen(port, host);
+    else probe.listen(port);
+  });
+}
+
+export async function findAvailablePort(startPort, options = {}) {
+  const maxAttempts = options.maxAttempts ?? DEFAULT_MAX_ATTEMPTS;
+  const host = options.host;
+  for (let offset = 0; offset <= maxAttempts; offset++) {
+    const port = Number(startPort) + offset;
+    try {
+      await checkPort(port, host);
+      return port;
+    } catch (err) {
+      if (err?.code !== "EADDRINUSE") throw err;
+    }
+  }
+  const err = new Error(`No available port found from ${startPort} to ${Number(startPort) + maxAttempts}`);
+  err.code = "PORT_RANGE_EXHAUSTED";
+  throw err;
+}
+
+function listenOnce(app, port, host) {
+  return new Promise((resolve, reject) => {
+    const server = host ? app.listen(port, host) : app.listen(port);
+    server.once("listening", () => resolve(server));
+    server.once("error", (err) => reject(err));
+  });
+}
+
+export async function listenWithPortFallback(app, startPort, options = {}) {
+  const maxAttempts = options.maxAttempts ?? DEFAULT_MAX_ATTEMPTS;
+  const host = options.host;
+  const label = options.label || "server";
+  for (let offset = 0; offset <= maxAttempts; offset++) {
+    const port = Number(startPort) + offset;
+    try {
+      const server = await listenOnce(app, port, host);
+      if (offset > 0 && typeof options.onFallback === "function") {
+        options.onFallback({ label, requestedPort: Number(startPort), actualPort: port });
+      }
+      return server;
+    } catch (err) {
+      if (err?.code !== "EADDRINUSE") throw err;
+      if (offset >= maxAttempts) {
+        const exhausted = new Error(`${label} port range exhausted from ${startPort} to ${port}`);
+        exhausted.code = "PORT_RANGE_EXHAUSTED";
+        exhausted.cause = err;
+        throw exhausted;
+      }
+    }
+  }
+  throw new Error(`${label} failed to bind`);
+}
+
+export function getServerPort(server) {
+  const address = server?.address?.();
+  return typeof address === "object" && address ? address.port : null;
+}

package/lib/sessionStore.js

@@ -94,6 +94,51 @@ function cleanData(v) {
   }
 }
 
+function normalizeGraphPayload(nodes, edges) {
+  const nodeIds = new Set(nodes.map((n) => n?.id).filter(Boolean).map(String));
+  const cleanEdges = edges.filter(
+    (e) => e?.id && e?.source && e?.target && nodeIds.has(String(e.source)) && nodeIds.has(String(e.target)),
+  );
+  const incomingByTarget = new Map();
+  for (const edge of cleanEdges) {
+    const target = String(edge.target);
+    if (incomingByTarget.has(target)) {
+      const err = new Error(`Node ${target} has multiple parent edges`);
+      err.code = "GRAPH_PARENT_CONFLICT";
+      err.status = 409;
+      throw err;
+    }
+    incomingByTarget.set(target, edge);
+  }
+
+  const nodeDataById = new Map();
+  for (const node of nodes) {
+    if (!node?.id) continue;
+    const data = node.data && typeof node.data === "object" && !Array.isArray(node.data)
+      ? { ...node.data }
+      : {};
+    nodeDataById.set(String(node.id), data);
+  }
+
+  const normalizedNodes = nodes.map((node) => {
+    if (!node?.id) return node;
+    const id = String(node.id);
+    const data = { ...(nodeDataById.get(id) ?? {}) };
+    const incoming = incomingByTarget.get(id);
+    if (!incoming) {
+      data.parentServerNodeId = null;
+    } else {
+      const parentData = nodeDataById.get(String(incoming.source)) ?? {};
+      data.parentServerNodeId = typeof parentData.serverNodeId === "string"
+        ? parentData.serverNodeId
+        : null;
+    }
+    return { ...node, data };
+  });
+
+  return { nodes: normalizedNodes, edges: cleanEdges };
+}
+
 export function saveGraph(sessionId, { nodes = [], edges = [], expectedVersion = null }) {
   const db = getDb();
   const sessionExists = db
@@ -124,11 +169,7 @@ export function saveGraph(sessionId, { nodes = [], edges = [], expectedVersion =
     throw err;
   }
 
-  // Validate edges reference existing nodes (drop dangling).
-  const nodeIds = new Set(nodes.map((n) => n?.id).filter(Boolean).map(String));
-  const cleanEdges = edges.filter(
-    (e) => e?.id && e?.source && e?.target && nodeIds.has(String(e.source)) && nodeIds.has(String(e.target)),
-  );
+  const normalized = normalizeGraphPayload(nodes, edges);
 
   const tx = db.transaction(() => {
     db.prepare("DELETE FROM nodes WHERE session_id = ?").run(sessionId);
@@ -137,7 +178,7 @@ export function saveGraph(sessionId, { nodes = [], edges = [], expectedVersion =
     const insNode = db.prepare(
       "INSERT INTO nodes (session_id, id, x, y, data) VALUES (?, ?, ?, ?, ?)",
     );
-    for (const n of nodes) {
+    for (const n of normalized.nodes) {
       if (!n?.id) continue;
       const x = Number(n.x ?? n.position?.x ?? 0);
       const y = Number(n.y ?? n.position?.y ?? 0);
@@ -153,7 +194,7 @@ export function saveGraph(sessionId, { nodes = [], edges = [], expectedVersion =
     const insEdge = db.prepare(
       "INSERT INTO edges (session_id, id, source, target, data) VALUES (?, ?, ?, ?, ?)",
     );
-    for (const e of cleanEdges) {
+    for (const e of normalized.edges) {
       insEdge.run(
         sessionId,
         cleanStr(String(e.id)),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ima2-gen",
-  "version": "1.1.0",
+  "version": "1.1.2",
   "description": "Local OAuth image generation studio with classic and node workflows",
   "type": "module",
   "bin": {
@@ -15,8 +15,9 @@
     "ui:build": "cd ui && npm run build",
     "build": "npm run ui:build",
     "test": "node scripts/run-tests.mjs",
+    "test:package-install": "node --test tests/package-install-smoke.mjs",
     "setup": "node bin/ima2.js setup",
-    "prepublishOnly": "npm run build && npm run lint:pkg",
+    "prepublishOnly": "npm test && npm run build && npm run test:package-install && npm run lint:pkg",
     "lint:pkg": "node -e \"const p=require('./package.json'); const req=['name','version','bin']; for(const k of req){if(!p[k])throw new Error('missing '+k)} const mustInclude=['bin/','lib/','routes/','server.js']; for(const f of mustInclude){if(!p.files.includes(f))throw new Error('files[] must include '+f)}\"",
     "release:patch": "npm version patch && npm publish && git push origin main --tags",
     "release:minor": "npm version minor && npm publish && git push origin main --tags",

package/routes/cardNews.js

@@ -0,0 +1,183 @@
+import { listImageTemplates, readTemplatePreview } from "../lib/cardNewsTemplateStore.js";
+import { listRoleTemplates } from "../lib/cardNewsRoleTemplateStore.js";
+import { createCardNewsDraft } from "../lib/cardNewsPlanner.js";
+import { generateCardNewsSet } from "../lib/cardNewsGenerator.js";
+import {
+  createCardNewsJob,
+  finishCardNewsJob,
+  getCardNewsJob,
+  getCardNewsJobPlan,
+  retryCardNewsJob,
+  updateCardNewsJob,
+  updateCardNewsJobCard,
+} from "../lib/cardNewsJobStore.js";
+import { listCardNewsSets, readCardNewsManifest, readCardNewsSetPlan } from "../lib/cardNewsManifestStore.js";
+
+function sendError(res, err) {
+  const status = err.status || 500;
+  res.status(status).json({
+    error: {
+      code: err.code || "CARD_NEWS_ERROR",
+      message: err.message || "Card News request failed",
+    },
+  });
+}
+
+function runCardNewsJob(ctx, jobId, plan) {
+  setImmediate(async () => {
+    try {
+      updateCardNewsJob(jobId, { status: "running" });
+      await generateCardNewsSet(ctx, plan, {
+        onCardStart: (card) => {
+          updateCardNewsJobCard(jobId, card.cardId, { status: "generating", error: undefined });
+        },
+        onCardDone: (card) => {
+          const url = card.imageFilename
+            ? `/generated/cardnews/${encodeURIComponent(card.setId)}/${encodeURIComponent(card.imageFilename)}`
+            : undefined;
+          updateCardNewsJobCard(jobId, card.cardId, {
+            status: card.status || "generated",
+            error: card.error?.message || card.error || undefined,
+            headline: card.headline,
+            body: card.body,
+            textFields: Array.isArray(card.textFields) ? card.textFields : [],
+            imageFilename: card.imageFilename || undefined,
+            generatedAt: card.generatedAt || undefined,
+            url,
+          });
+        },
+      });
+      finishCardNewsJob(jobId);
+    } catch (err) {
+      updateCardNewsJob(jobId, {
+        status: "error",
+        error: err.message || "Card News job failed",
+      });
+    }
+  });
+}
+
+export function registerCardNewsRoutes(app, ctx) {
+  app.get("/api/cardnews/image-templates", async (_req, res) => {
+    try {
+      res.json({ templates: await listImageTemplates(ctx) });
+    } catch (err) {
+      sendError(res, err);
+    }
+  });
+
+  app.get("/api/cardnews/image-templates/:templateId/preview", async (req, res) => {
+    try {
+      const buf = await readTemplatePreview(ctx, req.params.templateId);
+      res.type("image/png").send(buf);
+    } catch (err) {
+      sendError(res, err);
+    }
+  });
+
+  app.get("/api/cardnews/role-templates", (_req, res) => {
+    res.json({ templates: listRoleTemplates() });
+  });
+
+  app.get("/api/cardnews/sets", async (_req, res) => {
+    try {
+      res.json({ sets: await listCardNewsSets(ctx) });
+    } catch (err) {
+      sendError(res, err);
+    }
+  });
+
+  app.get("/api/cardnews/sets/:setId", async (req, res) => {
+    try {
+      res.json({ plan: await readCardNewsSetPlan(ctx, req.params.setId) });
+    } catch (err) {
+      sendError(res, err);
+    }
+  });
+
+  app.get("/api/cardnews/sets/:setId/manifest", async (req, res) => {
+    try {
+      const manifest = await readCardNewsManifest(ctx, req.params.setId);
+      if (req.query.download === "1") {
+        res.setHeader("Content-Disposition", `attachment; filename="${req.params.setId}-manifest.json"`);
+      }
+      res.type("application/json").send(JSON.stringify(manifest, null, 2));
+    } catch (err) {
+      sendError(res, err);
+    }
+  });
+
+  app.post("/api/cardnews/draft", async (req, res) => {
+    try {
+      res.json(await createCardNewsDraft(ctx, req.body || {}));
+    } catch (err) {
+      sendError(res, err);
+    }
+  });
+
+  app.post("/api/cardnews/generate", async (req, res) => {
+    try {
+      const result = await generateCardNewsSet(ctx, req.body || {});
+      res.json(result);
+    } catch (err) {
+      sendError(res, err);
+    }
+  });
+
+  app.post("/api/cardnews/jobs", (req, res) => {
+    try {
+      const summary = createCardNewsJob(req.body || {});
+      runCardNewsJob(ctx, summary.jobId, req.body || {});
+      res.status(202).json(summary);
+    } catch (err) {
+      sendError(res, err);
+    }
+  });
+
+  app.get("/api/cardnews/jobs/:jobId", (req, res) => {
+    const job = getCardNewsJob(req.params.jobId);
+    if (!job) {
+      res.status(404).json({ error: { code: "CARD_NEWS_JOB_NOT_FOUND", message: "Job not found" } });
+      return;
+    }
+    res.json(job);
+  });
+
+  app.post("/api/cardnews/jobs/:jobId/retry", (req, res) => {
+    const plan = getCardNewsJobPlan(req.params.jobId);
+    const job = retryCardNewsJob(req.params.jobId, req.body?.cardIds || []);
+    if (!job) {
+      res.status(404).json({ error: { code: "CARD_NEWS_JOB_NOT_FOUND", message: "Job not found" } });
+      return;
+    }
+    if (plan) {
+      const wanted = new Set(req.body?.cardIds || []);
+      runCardNewsJob(ctx, req.params.jobId, {
+        ...plan,
+        cards: (plan.cards || []).filter((card) => wanted.has(card.id)),
+      });
+    }
+    res.status(202).json(job);
+  });
+
+  app.post("/api/cardnews/cards/:cardId/regenerate", async (req, res) => {
+    try {
+      const body = req.body || {};
+      const cards = Array.isArray(body.cards)
+        ? body.cards.filter((card) => card.id === req.params.cardId || card.cardId === req.params.cardId)
+        : body.card ? [body.card] : [];
+      const result = await generateCardNewsSet(ctx, { ...body, cards });
+      res.json(result);
+    } catch (err) {
+      sendError(res, err);
+    }
+  });
+
+  app.post("/api/cardnews/export", (_req, res) => {
+    res.status(202).json({
+      ok: true,
+      status: "planned",
+      message: "Card News export is planned after the dev MVP generation slice.",
+    });
+  });
+}

package/routes/edit.js

@@ -19,7 +19,7 @@ function validateModeration(ctx, moderation) {
 
 export function registerEditRoutes(app, ctx) {
   app.post("/api/edit", async (req, res) => {
-    const requestId = typeof req.body?.requestId === "string" ? req.body.requestId : null;
+    const requestId = typeof req.body?.requestId === "string" ? req.body.requestId : req.id;
     let finishStatus = "completed";
     let finishHttpStatus;
     let finishErrorCode;

package/routes/generate.js

@@ -6,6 +6,7 @@ import { classifyUpstreamError } from "../lib/errorClassify.js";
 import { normalizeOAuthParams } from "../lib/oauthNormalize.js";
 import { normalizeImageModel } from "../lib/imageModels.js";
 import { generateViaOAuth } from "../lib/oauthProxy.js";
+import { normalizeGenerationFailure } from "../lib/generationErrors.js";
 import { startJob, finishJob } from "../lib/inflight.js";
 import { getStyleSheet } from "../lib/sessionStore.js";
 import { renderStyleSheetPrefix } from "../lib/styleSheet.js";
@@ -20,7 +21,7 @@ function validateModeration(ctx, moderation) {
 
 export function registerGenerateRoutes(app, ctx) {
   app.post("/api/generate", async (req, res) => {
-    const requestId = typeof req.body?.requestId === "string" ? req.body.requestId : null;
+    const requestId = typeof req.body?.requestId === "string" ? req.body.requestId : req.id;
     let finishStatus = "completed";
     let finishHttpStatus;
     let finishErrorCode;
@@ -150,11 +151,9 @@ export function registerGenerateRoutes(app, ctx) {
             logEvent("generate", "retry", { requestId, attempt: attempt + 1, errorCode: lastErr?.code });
           }
         }
-        const err = new Error("Content generation refused after retries");
-        err.code = "SAFETY_REFUSAL";
-        err.status = 422;
-        err.cause = lastErr;
-        throw err;
+        throw normalizeGenerationFailure(lastErr, {
+          safetyMessage: "Content generation refused after retries",
+        });
       };
 
       const results = await Promise.allSettled(Array.from({ length: count }, generateOne));
@@ -203,11 +202,12 @@ export function registerGenerateRoutes(app, ctx) {
 
       if (images.length === 0) {
         const firstErr = results.find((r) => r.status === "rejected")?.reason;
-        if (firstErr?.code === "SAFETY_REFUSAL") {
+        if (firstErr?.code) {
+          const status = firstErr.status || 500;
           finishStatus = "error";
-          finishHttpStatus = 422;
-          finishErrorCode = "SAFETY_REFUSAL";
-          return res.status(422).json({ error: firstErr.message, code: "SAFETY_REFUSAL" });
+          finishHttpStatus = status;
+          finishErrorCode = firstErr.code;
+          return res.status(status).json({ error: firstErr.message, code: firstErr.code, requestId });
         }
         finishStatus = "error";
         finishHttpStatus = 500;

package/routes/health.js

@@ -1,12 +1,29 @@
 import { listJobs, listTerminalJobs, finishJob } from "../lib/inflight.js";
 
 export function registerHealthRoutes(app, ctx) {
+  const runtimePorts = () => ({
+    backend: {
+      configuredPort: Number(ctx.serverConfiguredPort || ctx.config.server.port),
+      actualPort: Number(ctx.serverActualPort || ctx.config.server.port),
+      url: ctx.serverUrl || `http://localhost:${ctx.serverActualPort || ctx.config.server.port}`,
+    },
+    oauth: {
+      configuredPort: Number(ctx.oauthPort),
+      actualPort: Number(ctx.oauthActualPort || ctx.oauthPort),
+      url: ctx.oauthUrl,
+      status: ctx.oauthReadyState,
+    },
+  });
+
   app.get("/api/providers", (_req, res) => {
     res.json({
       apiKey: false,
       oauth: true,
       oauthPort: ctx.oauthPort,
+      oauthActualPort: ctx.oauthActualPort || ctx.oauthPort,
+      oauthUrl: ctx.oauthUrl,
       apiKeyDisabled: true,
+      runtime: runtimePorts(),
     });
   });
 
@@ -19,22 +36,29 @@ export function registerHealthRoutes(app, ctx) {
       activeJobs: listJobs().length,
       pid: process.pid,
       startedAt: ctx.startedAt,
+      runtime: runtimePorts(),
     });
   });
 
   app.get("/api/oauth/status", async (_req, res) => {
+    if (ctx.oauthReadyState === "starting") {
+      return res.json({ status: "starting", runtime: runtimePorts() });
+    }
+    if (ctx.oauthReadyState === "failed") {
+      return res.json({ status: "offline", runtime: runtimePorts() });
+    }
     try {
       const r = await fetch(`${ctx.oauthUrl}/v1/models`, {
         signal: AbortSignal.timeout(ctx.config.oauth.statusTimeoutMs),
       });
       if (r.ok) {
         const data = await r.json();
-        res.json({ status: "ready", models: data.data?.map((m) => m.id) || [] });
+        res.json({ status: "ready", models: data.data?.map((m) => m.id) || [], runtime: runtimePorts() });
       } else {
-        res.json({ status: "auth_required" });
+        res.json({ status: "auth_required", runtime: runtimePorts() });
       }
     } catch {
-      res.json({ status: "offline" });
+      res.json({ status: "offline", runtime: runtimePorts() });
     }
   });
 

package/routes/index.js

@@ -5,6 +5,7 @@ import { registerEditRoutes } from "./edit.js";
 import { registerNodeRoutes } from "./nodes.js";
 import { registerGenerateRoutes } from "./generate.js";
 import { registerStorageRoutes } from "./storage.js";
+import { registerCardNewsRoutes } from "./cardNews.js";
 
 export function configureRoutes(app, ctx) {
   registerHealthRoutes(app, ctx);
@@ -13,5 +14,6 @@ export function configureRoutes(app, ctx) {
   registerSessionRoutes(app, ctx);
   registerEditRoutes(app, ctx);
   registerNodeRoutes(app, ctx);
+  if (ctx.config.features.cardNews) registerCardNewsRoutes(app, ctx);
   registerGenerateRoutes(app, ctx);
 }