slidemind 0.3.13 → 0.3.14

package/src/bridge/client/brands.mjs

@@ -0,0 +1,622 @@
+// Brand routes: design bundles, brand listing, concept images, image generation,
+// convert-pptx, and the engine catalog.
+
+import { randomUUID } from "node:crypto";
+import path from "node:path";
+import { deriveEnvLabel } from "../config.mjs";
+import { resolveBackendForPres } from "./presentations.mjs";
+import { listTimeoutMs, engineTimeoutMs, withTransientRetry, sessionsInScope, sessionForBackend, bridgeFetch, backendCapabilities, backendSupportsBrandRoutes, backendSupportsConceptImages, backendSupportsImageGeneration, backendSupportsBrandsList, graphHeaders } from "./transport.mjs";
+
+// GET the full design bundle (tokens, css, layouts, designRules, signed asset
+// URLs, engines) for the presentation's active corporate design.
+export async function getDesignBundle(
+  presId,
+  { backendURL = null, preferBrandId = null } = {},
+) {
+  if (!presId) throw new Error("getDesignBundle: presId is required");
+  const be =
+    backendURL || (await resolveBackendForPres(presId, { preferBrandId }));
+  return withTransientRetry(async () => {
+    const res = await bridgeFetch(
+      `/api/cli/presentations/${encodeURIComponent(presId)}/design-bundle`,
+      {},
+      be,
+    );
+    return res.json();
+  });
+}
+
+// GET the design bundle by brandId over the pane-free brand route. 404
+// `unknown_brand` is definitive (unknown / cross-tenant / not granted to this
+// user), so no transient retry. Requires the resolved backendURL — use
+// getDesignBundleForBrandAnyBackend when it isn't known yet.
+export async function getDesignBundleForBrand(brandId, { backendURL } = {}) {
+  if (!brandId) {
+    throw new Error("getDesignBundleForBrand: brandId is required");
+  }
+  if (!backendURL) {
+    throw new Error("getDesignBundleForBrand: backendURL is required");
+  }
+  const res = await bridgeFetch(
+    `/api/cli/brands/${encodeURIComponent(brandId)}/design-bundle`,
+    {},
+    backendURL,
+  );
+  return res.json();
+}
+
+// Resolve WHICH paired backend serves a brand by asking each one that
+// advertises brand routes — a bound deck has no open window, so there is no
+// registry entry to resolve a backend from. presFP/brandId is globally unique
+// across deployments (the bundle-cache contract), so at most one backend
+// answers 2xx. Returns { wire, backendURL }; throws a typed
+// `brand_route_unavailable` when no backend serves the brand (old add-ins,
+// unknown brand, missing grant) so callers fall back to the pane flow.
+export async function getDesignBundleForBrandAnyBackend(brandId) {
+  if (!brandId) {
+    throw new Error("getDesignBundleForBrandAnyBackend: brandId is required");
+  }
+  const sessions = sessionsInScope();
+  const failures = [];
+  for (const s of sessions) {
+    try {
+      if (!(await backendSupportsBrandRoutes(s.backendURL))) {
+        failures.push({ env: deriveEnvLabel(s.backendURL), reason: "no brand routes" });
+        continue;
+      }
+      const wire = await getDesignBundleForBrand(brandId, {
+        backendURL: s.backendURL,
+      });
+      return { wire, backendURL: s.backendURL };
+    } catch (err) {
+      failures.push({
+        env: deriveEnvLabel(s.backendURL),
+        reason: err instanceof Error ? err.message : String(err),
+      });
+    }
+  }
+  const detail = failures.map((f) => `${f.env}: ${f.reason}`).join("; ");
+  const err = new Error(
+    `no paired backend serves design '${brandId}' over the pane-free brand ` +
+      `route${detail ? ` (${detail})` : ""}.`,
+  );
+  err.code = "brand_route_unavailable";
+  throw err;
+}
+
+// The corporate designs this user may build against, straight off the CLI
+// session — no open window, no pane. One entry per design: `{ presFP, name,
+// env }`, where presFP IS the brandId every pane-free route is keyed by. Only
+// backends advertising `brandsList` are asked (older ones have no such route);
+// a backend that fails is skipped rather than failing the whole answer, so one
+// unreachable environment can't hide another's designs.
+export async function listBrands() {
+  const out = [];
+  for (const s of sessionsInScope()) {
+    if (!(await backendSupportsBrandsList(s.backendURL))) continue;
+    const env = deriveEnvLabel(s.backendURL);
+    try {
+      const res = await bridgeFetch(
+        "/api/cli/brands",
+        { timeoutMs: listTimeoutMs() },
+        s.backendURL,
+      );
+      const data = (await res.json()) ?? {};
+      const arr = Array.isArray(data.brands) ? data.brands : [];
+      for (const b of arr) {
+        // The wire may name the design by either of its two equivalent keys
+        // (presFP on the bundle contract, brandId on the routes) — normalize to
+        // the one the deck ref stores.
+        const presFP = b?.presFP ?? b?.brandId ?? b?.id ?? null;
+        if (!presFP) continue;
+        out.push({
+          presFP,
+          name: b?.name ?? b?.designName ?? null,
+          env,
+          backendURL: s.backendURL,
+        });
+      }
+    } catch {
+      /* unreachable / not granted — that environment simply contributes none */
+    }
+  }
+  return out;
+}
+
+// Concept-image generation is a heavy provider call (per-image cap ~180s
+// server-side). Budget just over that so a typed server error wins over a
+// client timeout, but keep it below the relay's ~240s ingress cap — the CLI
+// batches per-slide so no single request approaches that ceiling.
+export function conceptTimeoutMs() {
+  return (
+    parseInt(process.env.SLIDEMIND_BRIDGE_CONCEPT_TIMEOUT_MS || "200000", 10) ||
+    200000
+  );
+}
+
+export async function postConceptImages(
+  brandId,
+  { planMarkdown, slideNumbers, references, force },
+  backendURL,
+) {
+  const body = { planMarkdown };
+  // `--force`: the server keeps a per-plan mockup cache; an unchanged plan
+  // would otherwise hand back last time's images no matter what changed
+  // server-side (prompt, chrome, model).
+  if (force) body.force = true;
+  if (Array.isArray(slideNumbers) && slideNumbers.length > 0) {
+    body.slideNumbers = slideNumbers;
+  }
+  // The user's own images, inline: `{ role: "concept" | "style", image:
+  // <data URI>, slides?: number[], name? }`. A concept replaces the generated
+  // mockup for its slides; a style reference leads the generation.
+  if (Array.isArray(references) && references.length > 0) {
+    body.references = references;
+  }
+  const res = await bridgeFetch(
+    `/api/cli/brands/${encodeURIComponent(brandId)}/concept-images`,
+    {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify(body),
+      timeoutMs: conceptTimeoutMs(),
+    },
+    backendURL,
+  );
+  const data = (await res.json()) ?? {};
+  // Tag the response with the backend that answered so a per-slide batch can
+  // pin subsequent calls to the same one (routing state only — never printed).
+  return { ...data, backendURL };
+}
+
+// Generate concept mockup images for a brand over the pane-free brand route.
+// Body `{ planMarkdown, slideNumbers?, references? }`; the optional `slideNumbers`
+// filters which storyboard beats are rendered (the CLI batches per-slide);
+// `references` carries the user's own concept/style images inline. Returns the
+// server's `{ ok, images, slideCount }` augmented with the resolved
+// `backendURL`. When `backendURL` is given it posts directly; otherwise it
+// fans out — like getDesignBundleForBrandAnyBackend, presFP/brandId is globally
+// unique so at most one paired backend answers 2xx. Throws a typed
+// `concept_route_unavailable` when no backend serves the brand (old add-ins,
+// unknown brand, missing grant) so callers can degrade to "continue without".
+export async function generateConceptImagesForBrand(
+  brandId,
+  {
+    planMarkdown,
+    slideNumbers = null,
+    references = null,
+    backendURL = null,
+    force = false,
+  } = {},
+) {
+  if (!brandId) {
+    throw new Error("generateConceptImagesForBrand: brandId is required");
+  }
+  if (typeof planMarkdown !== "string" || !planMarkdown.trim()) {
+    throw new Error("generateConceptImagesForBrand: planMarkdown is required");
+  }
+  if (backendURL) {
+    return postConceptImages(
+      brandId,
+      { planMarkdown, slideNumbers, references, force },
+      backendURL,
+    );
+  }
+  const sessions = sessionsInScope();
+  const failures = [];
+  for (const s of sessions) {
+    try {
+      if (!(await backendSupportsConceptImages(s.backendURL))) {
+        failures.push({
+          env: deriveEnvLabel(s.backendURL),
+          reason: "no concept-images route",
+        });
+        continue;
+      }
+      return await postConceptImages(
+        brandId,
+        { planMarkdown, slideNumbers, references, force },
+        s.backendURL,
+      );
+    } catch (err) {
+      failures.push({
+        env: deriveEnvLabel(s.backendURL),
+        reason: err instanceof Error ? err.message : String(err),
+      });
+    }
+  }
+  const detail = failures.map((f) => `${f.env}: ${f.reason}`).join("; ");
+  const err = new Error(
+    `no paired backend generates concept mockups for design '${brandId}'` +
+      `${detail ? ` (${detail})` : ""}.`,
+  );
+  err.code = "concept_route_unavailable";
+  throw err;
+}
+
+// Which connected backend generates concept mockups. One CAPABILITIES probe per
+// session answers it — cached, no image generated — which is why `concepts` can
+// go straight to its waves instead of spending a throwaway single-slide request
+// to learn who answers. Returns the one backend to pin a per-slide batch to, or
+// null when several environments qualify (developer machines only; each request
+// then fans out as before). Throws the typed `concept_route_unavailable` when
+// none does, so the caller degrades to "continue without".
+export async function resolveConceptBackend() {
+  const sessions = sessionsInScope();
+  const capable = [];
+  const failures = [];
+  for (const s of sessions) {
+    if (await backendSupportsConceptImages(s.backendURL)) {
+      capable.push(s.backendURL);
+    } else {
+      failures.push(`${deriveEnvLabel(s.backendURL)}: no concept-images route`);
+    }
+  }
+  if (capable.length === 0) {
+    const detail = failures.join("; ");
+    const err = new Error(
+      "no paired backend generates concept mockups" +
+        `${detail ? ` (${detail})` : ""}.`,
+    );
+    err.code = "concept_route_unavailable";
+    throw err;
+  }
+  return capable.length === 1 ? capable[0] : null;
+}
+
+// gpt-image calls routinely take 60-120s; budget like the concept relay so a
+// typed server error wins over a client timeout.
+export function imagenTimeoutMs() {
+  return (
+    parseInt(process.env.SLIDEMIND_BRIDGE_IMAGEN_TIMEOUT_MS || "200000", 10) ||
+    200000
+  );
+}
+
+export async function postGenerateImage(brandId, body, backendURL) {
+  const res = await bridgeFetch(
+    `/api/cli/brands/${encodeURIComponent(brandId)}/images`,
+    {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify(body),
+      timeoutMs: imagenTimeoutMs(),
+    },
+    backendURL,
+  );
+  const data = (await res.json()) ?? {};
+  return { ...data, backendURL };
+}
+
+// Generate ONE regular image over the pane-free brand route
+// (`slidemind imagen`). Body `{ prompt, size?, quality? }`;
+// returns the server's `{ ok, image }` augmented with the
+// resolved `backendURL`. Fan-out and degradation mirror
+// generateConceptImagesForBrand: throws a typed `imagen_route_unavailable`
+// when no paired backend serves the route (older add-ins, unknown brand,
+// missing grant) so callers can print the one actionable fix.
+export async function generateImageForBrand(
+  brandId,
+  { prompt, size = null, quality = null, backendURL = null } = {},
+) {
+  if (!brandId) {
+    throw new Error("generateImageForBrand: brandId is required");
+  }
+  if (typeof prompt !== "string" || !prompt.trim()) {
+    throw new Error("generateImageForBrand: prompt is required");
+  }
+  const body = { prompt };
+  if (size) body.size = size;
+  if (quality) body.quality = quality;
+  if (backendURL) {
+    return postGenerateImage(brandId, body, backendURL);
+  }
+  const sessions = sessionsInScope();
+  const failures = [];
+  for (const s of sessions) {
+    try {
+      if (!(await backendSupportsImageGeneration(s.backendURL))) {
+        failures.push({
+          env: deriveEnvLabel(s.backendURL),
+          reason: "no image-generation route (update the add-in)",
+        });
+        continue;
+      }
+      return await postGenerateImage(brandId, body, s.backendURL);
+    } catch (err) {
+      failures.push({
+        env: deriveEnvLabel(s.backendURL),
+        reason: err instanceof Error ? err.message : String(err),
+      });
+    }
+  }
+  const detail = failures.map((f) => `${f.env}: ${f.reason}`).join("; ");
+  const err = new Error(
+    `no paired backend generates images for design '${brandId}'` +
+      `${detail ? ` (${detail})` : ""}.`,
+  );
+  err.code = "imagen_route_unavailable";
+  throw err;
+}
+
+// Deterministic PPTX→JSX conversion is a per-slide OOXML parse + a render pass
+// per converted slide — a whole foreign deck runs in render-grade time, not
+// list-grade. Budget like the render routes.
+export function convertTimeoutMs() {
+  return (
+    parseInt(process.env.SLIDEMIND_BRIDGE_CONVERT_TIMEOUT_MS || "300000", 10) ||
+    300000
+  );
+}
+
+// Minimal multipart/form-data body. The route takes an uploaded PPTX, and
+// nodeRequest writes a Buffer verbatim — no fetch/FormData involved, so the
+// envelope is assembled here (fields first, file last, boundary never appearing
+// in the parts because it carries a random suffix).
+export function multipartBody(fields, file) {
+  const boundary = `----slidemind${randomUUID().replace(/-/g, "")}`;
+  const chunks = [];
+  for (const [name, value] of Object.entries(fields)) {
+    if (value === null || value === undefined) continue;
+    chunks.push(
+      Buffer.from(
+        `--${boundary}\r\nContent-Disposition: form-data; name="${name}"\r\n\r\n${value}\r\n`,
+      ),
+    );
+  }
+  // The file name reaches this from a path on disk; a quote or a newline in it
+  // would break out of the Content-Disposition header and forge a part.
+  const safeFileName = String(file.fileName).replace(/[\r\n"\\]/g, "_");
+  chunks.push(
+    Buffer.from(
+      `--${boundary}\r\nContent-Disposition: form-data; name="${file.name}"; ` +
+        `filename="${safeFileName}"\r\nContent-Type: ${file.contentType}\r\n\r\n`,
+    ),
+    Buffer.from(file.bytes),
+    Buffer.from(`\r\n--${boundary}--\r\n`),
+  );
+  return {
+    body: Buffer.concat(chunks),
+    contentType: `multipart/form-data; boundary=${boundary}`,
+  };
+}
+
+// Whether a backend deterministically converts foreign PPTX slides to jsx
+// (`POST /api/cli/brands/:brandId/convert-pptx`). Advertised only by add-ins
+// running with the reverse-conversion flag on; everywhere else `slidemind
+// adopt` folds untagged slides in as native .pptx exactly as before.
+export async function backendSupportsConvertPptx(backendURL) {
+  const caps = await backendCapabilities(backendURL);
+  return caps?.convertPptx === true;
+}
+
+export async function postConvertPptx(brandId, { bytes, fileName, slides }, backendURL) {
+  const { body, contentType } = multipartBody(
+    {
+      // 1-based play-order slide numbers to convert. Omitted = the whole deck;
+      // `adopt` always names the untagged ones so tagged slides are not re-parsed.
+      slides: Array.isArray(slides) && slides.length > 0 ? slides.join(",") : null,
+    },
+    {
+      name: "file",
+      fileName: path.basename(fileName || "deck.pptx"),
+      contentType:
+        "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+      bytes,
+    },
+  );
+  const res = await bridgeFetch(
+    `/api/cli/brands/${encodeURIComponent(brandId)}/convert-pptx`,
+    {
+      method: "POST",
+      headers: { "content-type": contentType },
+      body,
+      timeoutMs: convertTimeoutMs(),
+    },
+    backendURL,
+  );
+  const data = (await res.json()) ?? {};
+  return { ...data, backendURL };
+}
+
+// Convert a FILE deck's foreign slides to converted-dialect jsx over the
+// pane-free brand route (`slidemind adopt`). Body is multipart: the .pptx plus
+// the 1-based slide numbers to convert. Returns the server's
+// `{ slides, layouts, assets, sourceBaselines, conversionEvidence, skipped,
+// warnings }` (add-in `ConvertPptxResponse`) augmented with the resolved
+// `backendURL`. Identity and evidence are keyed by each slide's jsx `path`, not
+// carried on the slide — `src/lib/adopt.mjs` `convertedByNumber()` is the one
+// place that key shape is unfolded.
+//
+// LIVE decks are NOT convertible through this route in v1: converting an open
+// presentation needs a slide export + tag read over the relay, and neither
+// event exists (design D9) — the add-in path owns that flow.
+//
+// Fan-out and degradation mirror generateConceptImagesForBrand: throws a typed
+// `convert_route_unavailable` when no paired backend serves the route (older
+// add-ins, the reverse flag off, unknown brand, missing grant) so `adopt` falls
+// back to the native fold instead of failing.
+export async function convertPptxForBrand(
+  brandId,
+  { bytes, fileName = "deck.pptx", slides = null, backendURL = null } = {},
+) {
+  if (!brandId) throw new Error("convertPptxForBrand: brandId is required");
+  if (!bytes) throw new Error("convertPptxForBrand: bytes is required");
+  if (backendURL) {
+    return postConvertPptx(brandId, { bytes, fileName, slides }, backendURL);
+  }
+  const sessions = sessionsInScope();
+  const failures = [];
+  for (const s of sessions) {
+    try {
+      if (!(await backendSupportsConvertPptx(s.backendURL))) {
+        failures.push({
+          env: deriveEnvLabel(s.backendURL),
+          reason: "no convert-pptx route",
+        });
+        continue;
+      }
+      return await postConvertPptx(
+        brandId,
+        { bytes, fileName, slides },
+        s.backendURL,
+      );
+    } catch (err) {
+      failures.push({
+        env: deriveEnvLabel(s.backendURL),
+        reason: err instanceof Error ? err.message : String(err),
+      });
+    }
+  }
+  const detail = failures.map((f) => `${f.env}: ${f.reason}`).join("; ");
+  const err = new Error(
+    `no paired backend converts foreign slides for design '${brandId}'` +
+      `${detail ? ` (${detail})` : ""}.`,
+  );
+  err.code = "convert_route_unavailable";
+  throw err;
+}
+
+// List the LIVE engine catalog (NOT the bundle's curated set) for the paired
+// backend(s). `GET /api/cli/engines` is backend-scoped, not presId-scoped, so
+// when several environments are paired this fans out and tags each engine with
+// its short `env` label (never the backendURL — the no-URL rule). Filter by
+// engine `type` (collection|search) and/or `subtype` (image|slide|template|
+// content). Returns a flat `{ engines: [...], catalog }` like the single-backend
+// route.
+//
+// `catalog` is the pane-free route's summary — `{totalEngines, totalScopes,
+// filtered, emptyEngines}`, counted BEFORE the type/subtype filter — and it is
+// what separates "this filter matched nothing" from "this deployment has no
+// engines". Older backends (and the pane-relay path) send none; it stays null
+// there and every caller falls back to its pre-summary wording.
+export function readCatalogSummary(data) {
+  const c = data?.catalog;
+  if (!c || typeof c !== "object" || Array.isArray(c)) return null;
+  const num = (v) => (Number.isFinite(v) ? v : 0);
+  return {
+    totalEngines: num(c.totalEngines),
+    totalScopes: num(c.totalScopes),
+    filtered: Boolean(c.filtered),
+    emptyEngines: num(c.emptyEngines),
+  };
+}
+
+export async function listEnginesForBackend(backendURL, { type = null, subtype = null, signIn = true } = {}) {
+  return withTransientRetry(async () => {
+    const params = new URLSearchParams();
+    if (type) params.set("type", type);
+    if (subtype) params.set("subtype", subtype);
+    const qs = params.toString();
+    const res = await bridgeFetch(
+      `/api/cli/engines${qs ? `?${qs}` : ""}`,
+      // Pane-relayed on the add-in side — needs the engine budget, not the 8s
+      // list timeout (which bailed before the pane could ever answer). The
+      // delegated tokens authorize the pane-free catalog (login_required
+      // without them); older add-ins ignore the headers.
+      { timeoutMs: engineTimeoutMs(), headers: await graphHeaders(backendURL, { signIn }) },
+      backendURL,
+    );
+    const data = await res.json();
+    const arr = Array.isArray(data?.engines) ? data.engines : [];
+    const env = deriveEnvLabel(backendURL);
+    return {
+      engines: arr.map((e) => ({ ...e, env })),
+      catalog: readCatalogSummary(data),
+    };
+  });
+}
+
+// A scope (scope:all / scope:sharepoint) is not one environment's object: it is
+// the same saved search target, named identically on every deployment. Pooling
+// two backends' catalogs therefore repeats it verbatim — same id, same label —
+// which reads as two different things to choose between. Real engines DO differ
+// per environment and keep their duplicates; their `env` tag tells them apart.
+export function isScopeRow(e) {
+  return e?.type === "scope" || /^scope:/.test(String(e?.id ?? ""));
+}
+
+export async function listEngines({ type = null, subtype = null, backendURL = null } = {}) {
+  const sessions = backendURL ? [sessionForBackend(backendURL)] : sessionsInScope();
+  // Fanned out over several environments, the listing must not block on a
+  // browser sign-in for one of them — the user asked for a catalog, not for
+  // `local`'s Microsoft 365 login. One environment in scope keeps the
+  // automatic sign-in (that IS the environment being used).
+  const signIn = sessions.length === 1;
+  const settled = await Promise.allSettled(
+    sessions.map((s) => listEnginesForBackend(s.backendURL, { type, subtype, signIn })),
+  );
+  const engines = [];
+  const catalogs = [];
+  const failures = [];
+  // Which environments actually contributed. NOT derivable from the pooled rows
+  // any more: a second environment that only repeated the scopes leaves no row
+  // of its own, and the human renderer keys its `[env]` tags off this.
+  const envs = [];
+  // Scope id → the one pooled row kept for it.
+  const scopeRows = new Map();
+  let fulfilledCount = 0;
+  settled.forEach((r, i) => {
+    if (r.status === "fulfilled") {
+      fulfilledCount += 1;
+      envs.push(deriveEnvLabel(sessions[i].backendURL));
+      for (const e of r.value.engines) {
+        const id = typeof e?.id === "string" ? e.id : null;
+        if (id && isScopeRow(e)) {
+          const kept = scopeRows.get(id);
+          if (kept) {
+            // Contributed by more than one environment, so it belongs to none
+            // of them in particular — drop the tag rather than crediting
+            // whichever backend happened to answer first.
+            kept.env = null;
+            continue;
+          }
+          const row = { ...e };
+          scopeRows.set(id, row);
+          engines.push(row);
+          continue;
+        }
+        engines.push(e);
+      }
+      if (r.value.catalog) catalogs.push(r.value.catalog);
+    } else {
+      failures.push({ env: deriveEnvLabel(sessions[i].backendURL), err: r.reason });
+    }
+  });
+  // Mirror listOpenPresentations: only surface an error when nothing answered.
+  if (engines.length === 0 && fulfilledCount === 0 && failures.length > 0) {
+    if (failures.length === 1) throw failures[0].err;
+    throw new Error(
+      "slidemind: every paired backend failed to list engines:\n" +
+        failures.map((f) => `  ${f.env}: ${f.err.message}`).join("\n"),
+    );
+  }
+  // Fanned out, the summary is the sum of what each environment reported: the
+  // engines are pooled into one list, so their counts pool too. SCOPES are the
+  // exception — the same named targets everywhere, deduped above — so summing
+  // them double-counts; the distinct total is the largest environment's count,
+  // or the number of distinct scope rows actually pooled when that is larger.
+  // (The catalog counts are pre-filter and the rows post-filter, which is why
+  // both terms are needed.) `filtered` is the same question asked of every
+  // backend, so any one of them saying yes is the answer. Null when no backend
+  // supplied one (old add-in / pane relay).
+  const catalog = catalogs.length
+    ? {
+        totalEngines: catalogs.reduce((n, c) => n + c.totalEngines, 0),
+        totalScopes: Math.max(...catalogs.map((c) => c.totalScopes), scopeRows.size),
+        filtered: catalogs.some((c) => c.filtered),
+        emptyEngines: catalogs.reduce((n, c) => n + c.emptyEngines, 0),
+      }
+    : null;
+  return {
+    engines,
+    catalog,
+    envs,
+    failures: failures.map((f) => ({
+      env: f.env,
+      message: /login_required/.test(f.err?.message ?? "") || f.err?.code === "login_required"
+        ? `Microsoft 365 sign-in needed (run 'slidemind login --backend ${f.env}')`
+        : f.err?.message ?? String(f.err),
+    })),
+  };
+}