slidemind 0.1.8 → 0.2.0

package/src/bridge/client.mjs

@@ -51,6 +51,42 @@ export function compareCliVersions(a, b) {
   return 0;
 }
 
+// The one error every version-floor check raises, so the probe path
+// (assertCliVersionSupported) and the per-response header path are
+// indistinguishable to callers and to the skills that relay the text.
+function cliUpdateRequiredError(min) {
+  const err = new Error(
+    `slidemind CLI ${cliVersion()} is older than the minimum this add-in ` +
+      `supports (${min}). Run \`slidemind update\` (or ` +
+      "`npm install -g slidemind@latest`), then retry.",
+  );
+  err.code = "cli_update_required";
+  return err;
+}
+
+// `doctor` and `ready` exist to EXPLAIN a broken connection, version skew
+// included — they render it as a structured blocker with an `actor` and a
+// nextAction. Throwing the raw error out of bridgeFetch would break the one
+// command that diagnoses the problem, so they opt out of the header check
+// (their own ladder still reports cli_update_required, terminally).
+let diagnosticMode = false;
+export function setDiagnosticMode(on) {
+  diagnosticMode = on !== false;
+}
+
+// Every add-in response carries the version floor in `x-slidemind-min-cli`.
+// Checking it here covers routes no capability probe guards — the pane ops
+// (search/read/insert) and pairing itself — for zero extra round-trips, and it
+// fires BEFORE the status handling below so a stale CLI hitting a route that
+// does not exist yet reads "run slidemind update" instead of a bare 404.
+function enforceVersionFloor(response) {
+  if (diagnosticMode) return;
+  const min = response?.headers?.["x-slidemind-min-cli"];
+  if (typeof min !== "string" || !min) return;
+  if (compareCliVersions(cliVersion(), min) >= 0) return;
+  throw cliUpdateRequiredError(min);
+}
+
 function isLoopbackHostname(hostname) {
   return hostname === "127.0.0.1" || hostname === "localhost" || hostname === "::1";
 }
@@ -199,6 +235,7 @@ async function bridgeFetch(pathPart, init = {}, backendURL = null) {
     }
     throw err;
   }
+  enforceVersionFloor(response);
   if (response.status === 401) {
     throw new Error(
       "slidemind session is invalid or expired. Re-pair: open the add-in, " +
@@ -267,6 +304,7 @@ function nodeRequest(urlString, init = {}) {
           resolve({
             status: res.statusCode ?? 0,
             statusText: res.statusMessage ?? "",
+            headers: res.headers,
             body: Buffer.concat(chunks).toString("utf8"),
           });
         });
@@ -290,6 +328,163 @@ function nodeRequest(urlString, init = {}) {
   });
 }
 
+// A streaming sibling of `nodeRequest`, for responses too large to hold in
+// memory. `nodeRequest` concatenates the whole body and decodes it as UTF-8 —
+// fine for JSON, but it would both balloon memory and CORRUPT binary. This pipes
+// a success response straight to `destPath` and never materializes it.
+//
+// Error and JSON bodies are still buffered: both are small by construction (an
+// error message, or the inline SVG the download route answers with), and the
+// caller needs them whole to act on.
+function nodeRequestToFile(urlString, init = {}, destPath) {
+  const url = new URL(urlString);
+  const isHttps = url.protocol === "https:";
+  const transport = isHttps ? https : http;
+  const body = init.body ?? null;
+  const headers = { ...(init.headers ?? {}) };
+  if (
+    body &&
+    headers["content-length"] === undefined &&
+    headers["Content-Length"] === undefined
+  ) {
+    headers["content-length"] = Buffer.byteLength(body);
+  }
+  const timeoutMs =
+    init.timeoutMs ??
+    (parseInt(process.env.SLIDEMIND_BRIDGE_TIMEOUT_MS || "35000", 10) || 35000);
+
+  return new Promise((resolve, reject) => {
+    const req = transport.request(
+      url,
+      {
+        method: init.method ?? "GET",
+        headers,
+        rejectUnauthorized: isHttps
+          ? !isLoopbackHostname(url.hostname)
+          : undefined,
+      },
+      (res) => {
+        const status = res.statusCode ?? 0;
+        const contentType = String(res.headers["content-type"] ?? "");
+        const buffered = status < 200 || status >= 300 || contentType.includes("application/json");
+        if (buffered) {
+          const chunks = [];
+          res.on("data", (c) => chunks.push(Buffer.from(c)));
+          res.on("end", () =>
+            resolve({
+              status,
+              statusText: res.statusMessage ?? "",
+              headers: res.headers,
+              body: Buffer.concat(chunks).toString("utf8"),
+              streamed: false,
+            }),
+          );
+          res.on("error", reject);
+          return;
+        }
+        const out = fs.createWriteStream(destPath);
+        let bytesWritten = 0;
+        const total = Number.parseInt(
+          String(res.headers["content-length"] ?? ""),
+          10,
+        );
+        res.on("data", (c) => {
+          bytesWritten += c.length;
+          init.onProgress?.(bytesWritten, Number.isFinite(total) ? total : null);
+        });
+        res.pipe(out);
+        // A stream that dies mid-flight must reject, not resolve with a truncated
+        // file — the caller deletes the partial and surfaces the failure.
+        res.on("error", (err) => {
+          out.destroy();
+          reject(err);
+        });
+        out.on("error", reject);
+        out.on("finish", () =>
+          resolve({
+            status,
+            statusText: res.statusMessage ?? "",
+            headers: res.headers,
+            bytesWritten,
+            streamed: true,
+          }),
+        );
+      },
+    );
+    req.setTimeout(timeoutMs, () => {
+      const err = new Error(
+        `slidemind bridge request timed out after ${timeoutMs}ms`,
+      );
+      err.code = "bridge_timeout";
+      req.destroy(err);
+    });
+    req.on("error", reject);
+    if (body) req.write(body);
+    req.end();
+  });
+}
+
+// `bridgeFetch` for a response streamed to disk. Shares the session lookup,
+// auth header and non-2xx error mapping so a streaming call fails exactly like
+// every other bridge call.
+async function bridgeStreamToFile(pathPart, init, destPath, backendURL = null) {
+  const session = sessionForBackend(backendURL);
+  const url = `${session.backendURL}${pathPart}`;
+  const headers = {
+    accept: "application/octet-stream, application/json",
+    ...init.headers,
+    authorization: `Bearer ${session.sessionToken}`,
+  };
+  let response;
+  try {
+    response = await nodeRequestToFile(url, { ...init, headers }, destPath);
+  } catch (err) {
+    if (
+      err &&
+      /ECONNREFUSED|ECONNRESET|ENOTFOUND|self-signed|fetch failed/i.test(
+        String(err.message || err),
+      )
+    ) {
+      throw new Error(
+        `slidemind relay unreachable (${deriveEnvLabel(session.backendURL)}). Check your connection; ` +
+          "if it persists, re-pair with `slidemind pair`.",
+      );
+    }
+    throw err;
+  }
+  enforceVersionFloor(response);
+  if (response.status === 401) {
+    throw new Error(
+      "slidemind session is invalid or expired. Re-pair: open the add-in, " +
+        'click "Connect CLI", and run the shown `slidemind pair …`.',
+    );
+  }
+  if (response.status < 200 || response.status >= 300) {
+    let parsed = null;
+    try {
+      parsed = response.body ? JSON.parse(response.body) : null;
+    } catch {
+      /* non-JSON error body */
+    }
+    const machineCode =
+      parsed && typeof parsed.code === "string" ? parsed.code : null;
+    const humanError =
+      parsed && typeof parsed.error === "string" ? parsed.error : null;
+    const detail =
+      humanError ?? (response.body ? response.body.slice(0, 400) : "");
+    const err = new Error(
+      `slidemind bridge ${response.status} ${response.statusText} for ${pathPart}` +
+        (detail ? `: ${detail}` : ""),
+    );
+    err.status = response.status;
+    const code = machineCode ?? humanError;
+    if (code) err.code = code;
+    if (parsed) err.body = parsed;
+    throw err;
+  }
+  return response;
+}
+
 // List one backend's open presentations, tagging each entry with its origin
 // (backendURL + a short env label) so the merged registry can be routed and
 // displayed per environment. Transient blips retry per-backend.
@@ -789,6 +984,172 @@ export async function getDesignBundleForBrandAnyBackend(brandId) {
   throw err;
 }
 
+// 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.
+function conceptTimeoutMs() {
+  return (
+    parseInt(process.env.SLIDEMIND_BRIDGE_CONCEPT_TIMEOUT_MS || "200000", 10) ||
+    200000
+  );
+}
+
+async function postConceptImages(
+  brandId,
+  { planMarkdown, slideNumbers },
+  backendURL,
+) {
+  const body = { planMarkdown };
+  if (Array.isArray(slideNumbers) && slideNumbers.length > 0) {
+    body.slideNumbers = slideNumbers;
+  }
+  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? }`; the optional `slideNumbers` filters
+// which storyboard beats are rendered (the CLI batches per-slide). 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, backendURL = null } = {},
+) {
+  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 }, 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 },
+        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;
+}
+
+// gpt-image calls routinely take 60-120s; budget like the concept relay so a
+// typed server error wins over a client timeout.
+function imagenTimeoutMs() {
+  return (
+    parseInt(process.env.SLIDEMIND_BRIDGE_IMAGEN_TIMEOUT_MS || "200000", 10) ||
+    200000
+  );
+}
+
+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?, brandStyle? }`;
+// returns the server's `{ ok, image, styleReferences }` 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, brandStyle = false, 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 (brandStyle) body.brandStyle = true;
+  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;
+}
+
 // 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
@@ -905,6 +1266,23 @@ export async function backendSupportsBrandRoutes(backendURL) {
   return caps?.brandRoutes === true;
 }
 
+// Whether a backend generates concept mockup images for a brand over the
+// pane-free `/api/cli/brands/:brandId/concept-images` route (see
+// generateConceptImagesForBrand). Advertised by newer add-ins only; older ones
+// omit the flag and the caller degrades to "continue without".
+export async function backendSupportsConceptImages(backendURL) {
+  const caps = await backendCapabilities(backendURL);
+  return caps?.conceptImages === true;
+}
+
+// Whether a backend generates regular images over the pane-free
+// `/api/cli/brands/:brandId/images` route (see generateImageForBrand).
+// Advertised by newer add-ins only.
+export async function backendSupportsImageGeneration(backendURL) {
+  const caps = await backendCapabilities(backendURL);
+  return caps?.imageGeneration === true;
+}
+
 // The add-in's hard version floor: /api/cli/capabilities advertises the oldest
 // CLI it still speaks (`minCliVersion`). An older CLI must refuse to proceed —
 // mid-rollout skew otherwise surfaces as confusing route/contract errors deep
@@ -914,13 +1292,7 @@ export async function assertCliVersionSupported(backendURL) {
   const caps = await backendCapabilities(backendURL);
   const min = typeof caps?.minCliVersion === "string" ? caps.minCliVersion : null;
   if (!min || compareCliVersions(cliVersion(), min) >= 0) return;
-  const err = new Error(
-    `slidemind CLI ${cliVersion()} is older than the minimum this add-in ` +
-      `supports (${min}). Run \`slidemind update\` (or ` +
-      "`npm install -g slidemind@latest`), then retry.",
-  );
-  err.code = "cli_update_required";
-  throw err;
+  throw cliUpdateRequiredError(min);
 }
 
 // Rebuild a job failure into the exact error shape bridgeFetch throws for the
@@ -1231,11 +1603,17 @@ async function engineOpWithPaneWait(presId, backendURL, attempt) {
 // slide results carrying per-slide text + metadata). `subtype`/`intent`/`top`
 // are passed through for slide engines (image engines ignore intent); omit them
 // and the server uses its defaults (back-compat with older add-ins).
+//
+// `engineId` may also be a SCOPE sentinel (`scope:all` / `scope:sharepoint`) —
+// an unfiltered search over the whole corpus rather than one engine's saved
+// folder filter. A scope has no subtype to derive its index from, so it needs an
+// explicit `resultType`; the add-in rejects a scope search without one.
 export async function engineSearch({
   presId,
   engineId,
   query,
   subtype = null,
+  resultType = null,
   intent = null,
   top = null,
   backendURL = null,
@@ -1251,6 +1629,8 @@ export async function engineSearch({
   const be = backendURL || (await resolveBackendForPres(presId));
   const body = { engineId, query };
   if (subtype) body.subtype = subtype;
+  // Additive: omitted unless set, so the body an older add-in sees is unchanged.
+  if (resultType) body.resultType = resultType;
   if (intent) body.intent = intent;
   if (typeof top === "number") body.top = top;
   const run = async (pid, b) => {
@@ -1285,6 +1665,7 @@ export async function engineSearchAnyPane({
   engineId,
   query,
   subtype = null,
+  resultType = null,
   intent = null,
   top = null,
 }) {
@@ -1318,6 +1699,7 @@ export async function engineSearchAnyPane({
         engineId,
         query,
         subtype,
+        resultType,
         intent,
         top,
         backendURL: cand.backendURL ?? primaryBackend,
@@ -1384,6 +1766,130 @@ export async function engineDownload({
   });
 }
 
+// Stream a chosen engine result's bytes to `destPath`. The size-unbounded
+// download: the pane's Socket.IO ack carries only a signed source reference, and
+// the add-in server fetches it and pipes the body here — so nothing buffers the
+// whole image and there is no base64 4/3 inflation. `engineDownload` above sends
+// the bytes through the pane ack instead and is therefore capped by the relay's
+// 10 MB frame limit; prefer this for anything that might be large.
+//
+// An SVG result comes back as JSON (`{ ok, mimeType, svgMarkup }`) rather than a
+// byte stream: it is kilobytes and its recolour happens pane-side. Callers get
+// `{ svgMarkup }` in that case and `{ bytesWritten, mimeType }` otherwise, so they
+// can persist whichever arrived.
+export async function engineDownloadToFile({
+  presId,
+  searchId,
+  selection,
+  destPath,
+  iconColor = null,
+  backendURL = null,
+  onProgress = null,
+}) {
+  if (!presId) throw new Error("engineDownloadToFile: presId is required");
+  if (typeof searchId !== "number") {
+    throw new Error("engineDownloadToFile: searchId (number) is required");
+  }
+  if (typeof selection !== "number") {
+    throw new Error("engineDownloadToFile: selection (number) is required");
+  }
+  if (!destPath) throw new Error("engineDownloadToFile: destPath is required");
+  const be = backendURL || (await resolveBackendForPres(presId));
+  const body = { searchId, selection };
+  if (iconColor) body.iconColor = iconColor;
+  return engineOpWithPaneWait(presId, be, async (pid, b) => {
+    const res = await bridgeStreamToFile(
+      `/api/cli/presentations/${encodeURIComponent(pid)}/engine/download-stream`,
+      {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(body),
+        // A large image legitimately takes longer than an engine op: the server
+        // is fetching from SharePoint/blob AND piping. Separate budget so raising
+        // it doesn't loosen every other relay call.
+        timeoutMs:
+          parseInt(
+            process.env.SLIDEMIND_BRIDGE_DOWNLOAD_TIMEOUT_MS || "600000",
+            10,
+          ) || 600000,
+        onProgress,
+      },
+      destPath,
+      b,
+    );
+    if (!res.streamed) {
+      // The inline-SVG answer (kilobytes) arrives as JSON, not as a byte stream.
+      const parsed = res.body ? JSON.parse(res.body) : {};
+      return { ok: true, streamed: false, ...parsed };
+    }
+    const warningsHeader = res.headers?.["x-slidemind-warnings"];
+    let warnings;
+    if (warningsHeader) {
+      try {
+        warnings = JSON.parse(warningsHeader);
+      } catch {
+        // A malformed header must not fail a download that otherwise succeeded.
+      }
+    }
+    return {
+      ok: true,
+      streamed: true,
+      mimeType: String(res.headers?.["content-type"] ?? "") || null,
+      bytesWritten: res.bytesWritten,
+      ...(warnings ? { warnings } : {}),
+    };
+  });
+}
+
+// Stream a chosen slide-search result to `destPath` as a native one-slide .pptx.
+// The size-unbounded sibling of `extractSlide`: the pane ack carries only the
+// request, and the add-in server performs it and pipes the (base64-decoded) bytes
+// here. `extractSlide` puts the whole slide through the pane's Socket.IO ack as
+// base64, so it is capped at ~7 MB of real bytes — which real reused slides reach.
+export async function extractSlideToFile({
+  presId,
+  searchId,
+  selection,
+  destPath,
+  backendURL = null,
+  onProgress = null,
+}) {
+  if (!presId) throw new Error("extractSlideToFile: presId is required");
+  if (typeof searchId !== "number") {
+    throw new Error("extractSlideToFile: searchId (number) is required");
+  }
+  if (typeof selection !== "number") {
+    throw new Error("extractSlideToFile: selection (number) is required");
+  }
+  if (!destPath) throw new Error("extractSlideToFile: destPath is required");
+  const be = backendURL || (await resolveBackendForPres(presId));
+  return engineOpWithPaneWait(presId, be, async (pid, b) => {
+    const res = await bridgeStreamToFile(
+      `/api/cli/presentations/${encodeURIComponent(pid)}/engine/slide-extract-stream`,
+      {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ searchId, selection }),
+        timeoutMs:
+          parseInt(
+            process.env.SLIDEMIND_BRIDGE_DOWNLOAD_TIMEOUT_MS || "600000",
+            10,
+          ) || 600000,
+        onProgress,
+      },
+      destPath,
+      b,
+    );
+    const title = res.headers?.["x-slidemind-presentation-title"];
+    return {
+      ok: true,
+      bytesWritten: res.bytesWritten,
+      slideId: res.headers?.["x-slidemind-slide-id"] ?? undefined,
+      presentationTitle: title ? decodeURIComponent(String(title)) : undefined,
+    };
+  });
+}
+
 // Extract a chosen slide-search result as a standalone one-slide .pptx (base64),
 // WITHOUT inserting it anywhere — the "fold into a deck" path. Relayed through
 // the pane like search/download.