slidemind 0.3.12 → 0.3.14

package/src/bridge/client/engine-slides.mjs

@@ -0,0 +1,435 @@
+// Slide extraction, live insert, view and source-presentation reads off a search.
+
+import { randomUUID } from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { assertSearchId, downloadTimeoutMs, resultRoute, directEngineBackend } from "./engine-routing.mjs";
+import { insertSlides } from "./pane-ops.mjs";
+import { resolveBackendForPres, engineOpWithPaneWait } from "./presentations.mjs";
+import { engineTimeoutMs, bridgeFetch, bridgeStreamToFile, backendSupportsSourcePresentation, graphHeaders } from "./transport.mjs";
+
+// 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.
+//
+// With NO presId and a resolved `backendURL`/`brandId` this streams pane-free
+// from `GET /api/cli/searches/:searchId/results/:selection/slide`.
+export async function extractSlideToFile({
+  presId = null,
+  searchId,
+  selection,
+  destPath,
+  backendURL = null,
+  brandId = null,
+  onProgress = null,
+}) {
+  const direct = !presId && Boolean(backendURL || brandId);
+  if (!presId && !direct) throw new Error("extractSlideToFile: presId is required");
+  assertSearchId("extractSlideToFile", searchId);
+  if (typeof selection !== "number") {
+    throw new Error("extractSlideToFile: selection (number) is required");
+  }
+  if (!destPath) throw new Error("extractSlideToFile: destPath is required");
+  const shape = (res) => {
+    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,
+    };
+  };
+  if (direct) {
+    const b = await directEngineBackend("extractSlideToFile", {
+      backendURL,
+      brandId,
+    });
+    const res = await bridgeStreamToFile(
+      resultRoute(searchId, selection, "slide"),
+      {
+        method: "GET",
+        headers: await graphHeaders(b),
+        timeoutMs: downloadTimeoutMs(),
+        onProgress,
+      },
+      destPath,
+      b,
+    );
+    return shape(res);
+  }
+  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: downloadTimeoutMs(),
+        onProgress,
+      },
+      destPath,
+      b,
+    );
+    return shape(res);
+  });
+}
+
+// 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, and pane-only for the same reason as
+// engineDownload: the pane-free route streams (extractSlideToFile above), and
+// this capped ack path exists only for add-ins that predate it.
+export async function extractSlide({
+  presId,
+  searchId,
+  selection,
+  backendURL = null,
+}) {
+  if (!presId) throw new Error("extractSlide: presId is required");
+  assertSearchId("extractSlide", searchId);
+  if (typeof selection !== "number") {
+    throw new Error("extractSlide: selection (number) is required");
+  }
+  const be = backendURL || (await resolveBackendForPres(presId));
+  return engineOpWithPaneWait(presId, be, async (pid, b) => {
+    const res = await bridgeFetch(
+      `/api/cli/presentations/${encodeURIComponent(pid)}/engine/slide-extract`,
+      {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ searchId, selection }),
+        timeoutMs:
+          parseInt(process.env.SLIDEMIND_BRIDGE_ENGINE_TIMEOUT_MS || "90000", 10) ||
+          90000,
+      },
+      b,
+    );
+    return res.json(); // { ok, base64, slideId?, presentationTitle? }
+  });
+}
+
+// Insert one or more chosen slide-search results live into the open
+// presentation (the "reuse → insert live" path). Relayed through the pane.
+//
+// `fileName`/`brandId` identify the target WINDOW (brandId == the deck's presFP).
+// They cost nothing on the happy path and are what lets the single retry find
+// the same window again after a pane reconnect churned its presId — the same
+// self-healing `push` does around its insert.
+export async function insertSlideLive({
+  presId,
+  searchId,
+  selections,
+  at = null,
+  backendURL = null,
+  fileName = null,
+  brandId = null,
+  otherPresIds = null,
+}) {
+  if (!presId) throw new Error("insertSlideLive: presId is required");
+  assertSearchId("insertSlideLive", searchId);
+  if (!Array.isArray(selections) || selections.length === 0) {
+    throw new Error("insertSlideLive: selections (number[]) is required");
+  }
+  const be = backendURL || (await resolveBackendForPres(presId));
+  // Live insert is a MUTATION, so it carries an operationId for the add-in's
+  // runMutationOnce dedup (the slide-insert handler keys an LRU on it). Generate
+  // it ONCE here, before engineOpWithPaneWait — the body is built once and
+  // reused across the wrapper's single pane_suspended retry, so the SAME id
+  // rides both attempts and a retry can never double-insert. Mirrors how
+  // buildAndPush makes one push operationId reused across attempts.
+  const operationId = `insert-${randomUUID()}`;
+  const body = { searchId, selections, operationId };
+  if (typeof at === "number") body.at = at;
+  return engineOpWithPaneWait(
+    presId,
+    be,
+    async (pid, b) => {
+      const res = await bridgeFetch(
+        `/api/cli/presentations/${encodeURIComponent(pid)}/engine/slide-insert`,
+        {
+          method: "POST",
+          headers: { "content-type": "application/json" },
+          body: JSON.stringify(body),
+          timeoutMs:
+            parseInt(process.env.SLIDEMIND_BRIDGE_ENGINE_TIMEOUT_MS || "90000", 10) ||
+            90000,
+        },
+        b,
+      );
+      // Tag the window the insert actually landed in: after a retarget it is no
+      // longer the presId the caller passed, and the caller reports it.
+      return { ...(await res.json()), presId: pid }; // { ok, insertedCount, insertedSlideIds, presId }
+    },
+    // A vanished presId is recoverable HERE (unlike the engine reads, whose
+    // 404s are about the search record): the insert never landed, so re-listing
+    // and retrying against the re-registered window is safe — and the same
+    // operationId rides along, so even an ambiguous first attempt can't
+    // double-insert.
+    { fileName, brandId, otherPresIds, retargetOnMissing: true },
+  );
+}
+
+// Reuse chosen slide-search results live when the search record is the
+// BACKEND's rather than a pane's.
+//
+// The pane's slide-insert handler resolves a selection out of the in-browser
+// search context IT minted (a numeric id); a searchId from the pane-free search
+// is server-owned and opaque, so relaying it would answer `searchId_required`.
+// The two legs `add-slide --search` + `push` already run therefore do the job in
+// the other order: extract each pick pane-free, then hand the BYTES to the
+// window's own insert route. Live insert stays pane-bound (Office.js is the only
+// thing that can type into an open deck) — only the searchId resolution moves.
+export async function insertSlidesFromSearch({
+  presId,
+  searchId,
+  selections,
+  at = null,
+  backendURL = null,
+  engineBackendURL = null,
+  fileName = null,
+  brandId = null,
+  otherPresIds = null,
+  onProgress = null,
+}) {
+  if (!presId) throw new Error("insertSlidesFromSearch: presId is required");
+  assertSearchId("insertSlidesFromSearch", searchId);
+  if (!Array.isArray(selections) || selections.length === 0) {
+    throw new Error("insertSlidesFromSearch: selections (number[]) is required");
+  }
+  const be = backendURL || (await resolveBackendForPres(presId));
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "slidemind-reuse-"));
+  try {
+    let insertedCount = 0;
+    let livePresId = presId;
+    let liveBackendURL = be;
+    const insertedSlideIds = [];
+    for (const [i, selection] of selections.entries()) {
+      const slidePath = path.join(dir, `pick-${selection}.pptx`);
+      const extracted = await extractSlideToFile({
+        searchId,
+        selection,
+        destPath: slidePath,
+        backendURL: engineBackendURL,
+        brandId,
+        onProgress,
+      });
+      if (!extracted?.bytesWritten) {
+        throw new Error(`selection ${selection} produced no slide bytes`);
+      }
+      // One insert per pick, each with its own dedup key, so a retry inside
+      // engineOpWithPaneWait re-sends THAT pick and nothing else. `at` counts
+      // forward so the picks land in the order they were named.
+      const operationId = `insert-${randomUUID()}`;
+      const base64 = fs.readFileSync(slidePath).toString("base64");
+      const resp = await engineOpWithPaneWait(
+        livePresId,
+        liveBackendURL,
+        async (pid, b) => {
+          const ack = await insertSlides({
+            presId: pid,
+            base64,
+            insertAt: typeof at === "number" ? at + i : null,
+            sourceSlideIds: extracted.slideId ? [extracted.slideId] : null,
+            operationId,
+            backendURL: b,
+          });
+          return { ...ack, presId: pid, backendURL: b };
+        },
+        { fileName, brandId, otherPresIds, retargetOnMissing: true },
+      );
+      // A retarget moves every remaining pick to the window that answered, so
+      // a multi-pick reuse cannot end up split across two presentations.
+      livePresId = resp.presId ?? livePresId;
+      liveBackendURL = resp.backendURL ?? liveBackendURL;
+      const landed = Array.isArray(resp.insertedSlideIds)
+        ? resp.insertedSlideIds
+        : [];
+      insertedCount += landed.length || 1;
+      insertedSlideIds.push(...landed);
+      bestEffortRm(slidePath);
+    }
+    return { ok: true, insertedCount, insertedSlideIds, presId: livePresId };
+  } finally {
+    bestEffortRm(dir);
+  }
+}
+
+// Remove a temp file/dir that bytes were JUST streamed into. Windows may still
+// hold a handle on it at cleanup time (antivirus scanning the fresh write), so
+// plain rmSync races into EBUSY/ENOTEMPTY there — retry, and swallow what's
+// left: cleanup failure must never mask an operation that succeeded.
+export function bestEffortRm(p) {
+  try {
+    fs.rmSync(p, { recursive: true, force: true, maxRetries: 5, retryDelay: 100 });
+  } catch {}
+}
+
+// Fetch a chosen slide-search result's thumbnail/preview as a data URI for
+// on-demand viewing (the agent doesn't have to extract the whole .pptx just to
+// look at a slide). Relayed through the pane.
+//
+// With NO presId and a resolved `backendURL`/`brandId` this reads the pane-free
+// `GET …/results/:selection/thumbnail`, which STREAMS: a thumbnail is small, so
+// it is buffered back into the same `{ dataUri }` contract rather than forcing
+// every caller to grow a file path.
+export async function viewSlide({
+  presId = null,
+  searchId,
+  selection,
+  backendURL = null,
+  brandId = null,
+}) {
+  const direct = !presId && Boolean(backendURL || brandId);
+  if (!presId && !direct) throw new Error("viewSlide: presId is required");
+  assertSearchId("viewSlide", searchId);
+  if (typeof selection !== "number") {
+    throw new Error("viewSlide: selection (number) is required");
+  }
+  if (direct) {
+    const b = await directEngineBackend("viewSlide", { backendURL, brandId });
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "slidemind-thumb-"));
+    const tmp = path.join(dir, "thumbnail.bin");
+    try {
+      const res = await bridgeStreamToFile(
+        resultRoute(searchId, selection, "thumbnail"),
+        {
+          method: "GET",
+          headers: await graphHeaders(b),
+          timeoutMs: engineTimeoutMs(),
+        },
+        tmp,
+        b,
+      );
+      if (!res.streamed) {
+        // An add-in that answers with an inline preview passes straight through.
+        return res.body ? JSON.parse(res.body) : { ok: false };
+      }
+      const mimeType =
+        String(res.headers?.["content-type"] ?? "").split(";")[0].trim() ||
+        "image/png";
+      return {
+        ok: true,
+        mimeType,
+        dataUri: `data:${mimeType};base64,${fs.readFileSync(tmp).toString("base64")}`,
+      };
+    } finally {
+      bestEffortRm(dir);
+    }
+  }
+  const be = backendURL || (await resolveBackendForPres(presId));
+  return engineOpWithPaneWait(presId, be, async (pid, b) => {
+    const res = await bridgeFetch(
+      `/api/cli/presentations/${encodeURIComponent(pid)}/engine/slide-view`,
+      {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ searchId, selection }),
+        timeoutMs:
+          parseInt(process.env.SLIDEMIND_BRIDGE_ENGINE_TIMEOUT_MS || "90000", 10) ||
+          90000,
+      },
+      b,
+    );
+    return res.json(); // { ok, dataUri, mimeType }
+  });
+}
+
+// Read the ORIGINAL deck a chosen slide-search result came from — NOT the open
+// window (that is getPresentationContent below). Answers "what else is in the
+// presentation this slide belongs to?": the surrounding narrative, the slides
+// either side, the argument the source deck was making.
+//
+// The add-in reads it out of the slide index rather than downloading the source
+// file, so this is fast and works the same for blob- and SharePoint-backed
+// results — but the text is the last SYNCED extraction, not the live file. The
+// response is Markdown, and the pane never carries it: the relay route resolves
+// the selection through the pane and performs the backend read itself.
+//
+// searchId is presentation-scoped on the pane path, so that path relays through
+// the window the search ran on, like viewSlide. Idempotent, so the
+// pane_suspended retry is safe. With NO presId and a resolved
+// `backendURL`/`brandId` it reads the pane-free
+// `GET …/results/:selection/source-presentation` instead (the searchId is
+// server-owned there, so no window is involved at all).
+export async function readSourcePresentation({
+  presId = null,
+  searchId,
+  selection,
+  fromSlide = null,
+  toSlide = null,
+  backendURL = null,
+  brandId = null,
+}) {
+  const direct = !presId && Boolean(backendURL || brandId);
+  if (!presId && !direct) {
+    throw new Error("readSourcePresentation: presId is required");
+  }
+  assertSearchId("readSourcePresentation", searchId);
+  if (typeof selection !== "number") {
+    throw new Error("readSourcePresentation: selection (number) is required");
+  }
+  // Both paths answer with Markdown plus the counts/truncation in headers.
+  const shape = async (res) => ({
+    ok: true,
+    markdown: await res.text(),
+    truncated: res.headers?.["x-slidemind-truncated"] === "1",
+    slideCount: Number(res.headers?.["x-slidemind-slide-count"] ?? 0) || 0,
+    totalSlideCount:
+      Number(res.headers?.["x-slidemind-total-slide-count"] ?? 0) || 0,
+    presentationTitle: res.headers?.["x-slidemind-presentation-title"]
+      ? decodeURIComponent(String(res.headers["x-slidemind-presentation-title"]))
+      : undefined,
+  });
+  if (direct) {
+    // The direct route table carries source-presentation, so engineRoutes is the
+    // capability that gates it here (sourcePresentation gates the pane route).
+    const b = await directEngineBackend("readSourcePresentation", {
+      backendURL,
+      brandId,
+    });
+    const params = new URLSearchParams();
+    if (typeof fromSlide === "number") params.set("fromSlide", String(fromSlide));
+    if (typeof toSlide === "number") params.set("toSlide", String(toSlide));
+    const res = await bridgeFetch(
+      resultRoute(searchId, selection, "source-presentation", params),
+      {
+        method: "GET",
+        headers: { accept: "text/markdown, text/plain" },
+        timeoutMs: engineTimeoutMs(),
+      },
+      b,
+    );
+    return shape(res);
+  }
+  const be = backendURL || (await resolveBackendForPres(presId));
+  if (!(await backendSupportsSourcePresentation(be))) {
+    const err = new Error(
+      "This slidemind add-in cannot read a result's source presentation yet. Update the add-in, then try again.",
+    );
+    err.code = "source_presentation_unsupported";
+    throw err;
+  }
+  const body = { searchId, selection };
+  if (typeof fromSlide === "number") body.fromSlide = fromSlide;
+  if (typeof toSlide === "number") body.toSlide = toSlide;
+  return engineOpWithPaneWait(presId, be, async (pid, b) => {
+    const res = await bridgeFetch(
+      `/api/cli/presentations/${encodeURIComponent(pid)}/source-presentation`,
+      {
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+          accept: "text/markdown, text/plain",
+        },
+        body: JSON.stringify(body),
+        timeoutMs: engineTimeoutMs(),
+      },
+      b,
+    );
+    return shape(res);
+  });
+}