slidemind 0.2.4 → 0.3.0

package/src/bridge/client.mjs

@@ -16,9 +16,16 @@ import { fileURLToPath } from "node:url";
 
 import {
   deriveEnvLabel,
+  envPhrase,
   getSessionFor,
+  isMultiEnv,
   readSessions,
 } from "./config.mjs";
+import {
+  ensureSignedIn,
+  getGraphToken,
+  getSharePointToken,
+} from "./graph-auth.mjs";
 import { updateCliInstruction } from "../install-channel.mjs";
 
 // This CLI's own version, for the add-in's minCliVersion floor (see
@@ -254,7 +261,7 @@ async function bridgeFetch(pathPart, init = {}, backendURL = null) {
   } 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; ` +
+        `slidemind relay unreachable${envPhrase(deriveEnvLabel(session.backendURL), "on")}. Check your connection; ` +
           "if it persists, reconnect from the add-in's Connect CLI panel.",
       );
     }
@@ -470,7 +477,7 @@ async function bridgeStreamToFile(pathPart, init, destPath, backendURL = null) {
       )
     ) {
       throw new Error(
-        `slidemind relay unreachable (${deriveEnvLabel(session.backendURL)}). Check your connection; ` +
+        `slidemind relay unreachable${envPhrase(deriveEnvLabel(session.backendURL), "on")}. Check your connection; ` +
           "if it persists, reconnect from the add-in's Connect CLI panel.",
       );
     }
@@ -1258,6 +1265,144 @@ export async function generateImageForBrand(
   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.
+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).
+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;
+}
+
+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
@@ -1292,8 +1437,10 @@ async function listEnginesForBackend(backendURL, { type = null, subtype = null }
     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).
-      { timeoutMs: engineTimeoutMs() },
+      // 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) },
       backendURL,
     );
     const data = await res.json();
@@ -1503,6 +1650,16 @@ export async function backendSupportsEngineRoutes(backendURL) {
   return caps?.engineRoutes === true;
 }
 
+// Whether a backend honours a delegated Microsoft Graph token on the pane-free
+// engine routes — the CLI's own identity for SharePoint-backed content
+// (`slidemind login`, src/bridge/graph-auth.mjs). Gates BOTH the attach and the
+// remediation text: naming `slidemind login` on an add-in that ignores the token
+// would send a user through a browser flow that changes nothing.
+export async function backendSupportsGraphDelegated(backendURL) {
+  const caps = await backendCapabilities(backendURL);
+  return caps?.graphDelegated === 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
@@ -1698,6 +1855,9 @@ export async function renderPptx({
   deckAssets = null,
   nativeSlides = null,
   etag = null,
+  sourceGuids = null,
+  conversions = null,
+  reconcile = null,
   backendURL = null,
   onProgress = null,
 }) {
@@ -1728,6 +1888,30 @@ export async function renderPptx({
   // server splices them in by numeric-aware sorted filename (contract #7).
   if (hasNative) body.nativeSlides = nativeSlides;
   if (etag) body.etag = etag;
+  // Deck-embedded source: known slide GUIDs (jsx path → sm-<uuid>) so the
+  // server's tag bake keeps identities stable; minted ones ride back as
+  // `sourceGuids` on the response.
+  if (sourceGuids && Object.keys(sourceGuids).length > 0) {
+    body.sourceGuids = sourceGuids;
+  }
+  // Reverse-converted slides (`slidemind adopt`): identity + fidelity evidence
+  // per converted jsx file, so the server can gate the first replacement of a
+  // converted slide against what it originally converted, plus the verbatim
+  // source package whose preserved natives (chart / OLE / SmartArt) it splices
+  // back into the rendered slide. Keyed exactly like `slides`. Additive: a deck
+  // with no conversions sends the same body it always did.
+  if (conversions && Object.keys(conversions).length > 0) {
+    body.conversions = conversions;
+  }
+  // Manual-edit reconcile: for every slide the user edited in PowerPoint since
+  // the last build, the baked baseline projection and the current one, keyed
+  // exactly like `slides`. The server diffs them, folds text edits into the jsx
+  // it renders, and reports the rest — the CLI owns no diff source. Additive: a
+  // deck with no pending edits sends the same body it always did, and the
+  // response's `reconcile` echo is what proves the backend understood it.
+  if (reconcile && Object.keys(reconcile).length > 0) {
+    body.reconcile = reconcile;
+  }
   // The brand surface has no presId to label the render with — pass the deck
   // slug so job records/temp dirs stay readable (server-side sanitized).
   if (brandId && deckName) body.deckName = deckName;
@@ -1962,12 +2146,12 @@ export async function resolveSearchBackend(searchId) {
     }
   }
   // The two failures that are NOT the record talking: a dead session, and a
-  // permission snapshot that has aged out (the record re-read is an engine
-  // route, so it degrades with the rest of corpus search). Reported as "that
-  // search expired", both send the user to re-run a search that fails the same
-  // way — so they outrank the expired-record answer.
+  // missing Microsoft 365 sign-in (the record re-read is an engine route, so
+  // it refuses with the rest of corpus search). Reported as "that search
+  // expired", both send the user to re-run a search that fails the same way —
+  // so they outrank the expired-record answer.
   const blocking = failures.find(
-    (e) => isSessionInvalidError(e) || e?.code === "permissions_stale",
+    (e) => isSessionInvalidError(e) || e?.code === "login_required",
   );
   if (blocking) throw blocking;
   return null;
@@ -2072,27 +2256,91 @@ async function directEngineBackend(fn, { backendURL = null, brandId = null }) {
   throw err;
 }
 
-// The permission SNAPSHOT behind corpus search is refreshed whenever the add-in
-// runs; when it ages out the engine routes answer
-// `403 { error: "permissions_stale", action: "…" }` and only corpus search
-// degrades (render/bundle never do). Shape it like the connection ladder's rungs
-// — `{ code, actor, message }` — so the CLI can print ONE actionable line and an
-// agent knows it cannot clear this one itself. Returns null for any other error.
-export function permissionsStaleBlocker(err) {
-  if (err?.code !== "permissions_stale") return null;
+// The user's delegated tokens for a backend, or nulls. Attached ONLY to the
+// pane-free engine ops: they are the user's own Entra identity, and render,
+// bundle, whoami and the pane relay have no business carrying them (the pane
+// signs its own requests with a browser token that is strictly fresher).
+//
+// When nothing is stored, the sign-in RUNS HERE — browser opens, the command
+// blocks until the human finishes (graph-auth.ensureSignedIn, once per
+// process). So login is not a separate ritual: the first engine command of a
+// fresh machine walks the user through it, and every later one rides the
+// stored refresh token silently. Null only when the add-in doesn't honour the
+// tokens, or the sign-in was refused/abandoned — the backend then answers its
+// typed `login_required`, which the blocker below renders.
+async function engineGraphToken(backendURL) {
+  if (!backendURL) return null;
+  if (!(await backendSupportsGraphDelegated(backendURL))) return null;
+  let token = await getGraphToken(backendURL);
+  if (!token && (await ensureSignedIn(backendURL))) {
+    token = await getGraphToken(backendURL);
+  }
+  return token;
+}
+
+// The SharePoint-resource sibling (same sign-in, same refresh token): the
+// backend resolves `sg:` site-group membership from the PAIR, and on a
+// SharePoint-configured deployment refuses corpus search without it.
+async function engineSpToken(backendURL) {
+  if (!backendURL) return null;
+  if (!(await backendSupportsGraphDelegated(backendURL))) return null;
+  let token = await getSharePointToken(backendURL);
+  if (!token && (await ensureSignedIn(backendURL))) {
+    token = await getSharePointToken(backendURL);
+  }
+  return token;
+}
+
+// Both delegated tokens as body fields, for the POST routes. Empty when there
+// is nothing to attach, so an older backend sees the body it always did.
+async function delegatedBodyFields(backendURL) {
+  const [graphToken, spToken] = await Promise.all([
+    engineGraphToken(backendURL),
+    engineSpToken(backendURL),
+  ]);
+  return {
+    ...(graphToken ? { graphApiToken: graphToken } : {}),
+    ...(spToken ? { spApiToken: spToken } : {}),
+  };
+}
+
+// The byte routes are GETs, so the delegated tokens ride headers instead of
+// body fields. Empty (not absent-valued) when there is no token, so the request
+// headers are unchanged for everyone who never signed in.
+async function graphHeaders(backendURL) {
+  const [graphToken, spToken] = await Promise.all([
+    engineGraphToken(backendURL),
+    engineSpToken(backendURL),
+  ]);
+  return {
+    ...(graphToken ? { "x-slidemind-graph-token": graphToken } : {}),
+    ...(spToken ? { "x-slidemind-sp-token": spToken } : {}),
+  };
+}
+
+// Corpus search runs as the USER: the pane-free engine routes resolve the
+// caller's group membership live from the delegated tokens `slidemind login`
+// minted, and answer `401 { code: "login_required", action: "…" }` without
+// them. Shape it like the connection ladder's rungs — `{ code, actor, message }`
+// — so the CLI can print ONE actionable line and an agent knows it cannot clear
+// this one itself (the sign-in needs a browser and a human). Returns null for
+// any other error.
+export function loginRequiredBlocker(err) {
+  if (err?.code !== "login_required") return null;
   const action =
     typeof err?.body?.action === "string" && err.body.action.trim()
       ? err.body.action.trim()
-      : "open the slidemind add-in once to refresh access";
+      : "run `slidemind login` to sign in to Microsoft 365";
   return {
-    code: "permissions_stale",
+    code: "login_required",
     actor: "user",
     message:
-      `slidemind needs your search permissions refreshed before it can search the corpus — ${action}. ` +
+      `slidemind needs your Microsoft 365 sign-in before it can search the corpus — ${action}. ` +
       "Everything else (render, bundle, imagery already downloaded) keeps working.",
   };
 }
 
+
 // Brand-engine search through the local bridge. New add-ins run this
 // server-side with the relayed user token; older add-ins may fall back to a
 // task-pane proxy. Returns a searchId + numbered results (image thumbnails, or
@@ -2136,12 +2384,18 @@ export async function engineSearch({
   if (typeof top === "number") body.top = top;
   if (direct) {
     const be = await directEngineBackend("engineSearch", { backendURL, brandId });
+    // The user's own identity: the backend resolves the caller's group
+    // membership from these tokens per request and refuses without them
+    // (login_required). Search also seeds the speculative insert cache
+    // server-side, which is why it carries the Graph token as well as the
+    // byte GETs.
+    const delegated = await delegatedBodyFields(be);
     const res = await bridgeFetch(
       "/api/cli/searches",
       {
         method: "POST",
         headers: { "content-type": "application/json" },
-        body: JSON.stringify(body),
+        body: JSON.stringify({ ...body, ...delegated }),
         timeoutMs: timeoutMs ?? engineTimeoutMs(),
       },
       be,
@@ -2359,7 +2613,12 @@ export async function engineDownloadToFile({
     if (iconColor) params.set("iconColor", iconColor);
     const res = await bridgeStreamToFile(
       resultRoute(searchId, selection, "image", params),
-      { method: "GET", timeoutMs: downloadTimeoutMs(), onProgress },
+      {
+        method: "GET",
+        headers: await graphHeaders(b),
+        timeoutMs: downloadTimeoutMs(),
+        onProgress,
+      },
       destPath,
       b,
     );
@@ -2425,7 +2684,12 @@ export async function extractSlideToFile({
     });
     const res = await bridgeStreamToFile(
       resultRoute(searchId, selection, "slide"),
-      { method: "GET", timeoutMs: downloadTimeoutMs(), onProgress },
+      {
+        method: "GET",
+        headers: await graphHeaders(b),
+        timeoutMs: downloadTimeoutMs(),
+        onProgress,
+      },
       destPath,
       b,
     );
@@ -2657,7 +2921,11 @@ export async function viewSlide({
     try {
       const res = await bridgeStreamToFile(
         resultRoute(searchId, selection, "thumbnail"),
-        { method: "GET", timeoutMs: engineTimeoutMs() },
+        {
+          method: "GET",
+          headers: await graphHeaders(b),
+          timeoutMs: engineTimeoutMs(),
+        },
         tmp,
         b,
       );
@@ -2837,12 +3105,18 @@ export async function insertSlides({
   insertAt = null,
   sourceSlideIds = null,
   operationId = null,
+  sourceTagsBySlide = null,
   backendURL = null,
 }) {
   if (!presId) throw new Error("insertSlides: presId is required");
   if (!base64) throw new Error("insertSlides: base64 is required");
   const be = backendURL || (await resolveBackendForPres(presId));
   const body = { base64, insertAt, sourceSlideIds, operationId };
+  // Deck-embedded source payloads for the pane's post-insert tag write,
+  // aligned with the inserted slides in document order.
+  if (Array.isArray(sourceTagsBySlide) && sourceTagsBySlide.some(Boolean)) {
+    body.sourceTagsBySlide = sourceTagsBySlide;
+  }
   const res = await bridgeFetch(
     `/api/cli/presentations/${encodeURIComponent(presId)}/insert`,
     {
@@ -2858,21 +3132,65 @@ export async function insertSlides({
   return ensurePaneAckOk(await res.json().catch(() => ({})), "insert");
 }
 
+// Read-only sibling of the mutation ops: export the LIVE slides carrying the
+// given GUIDs, so a `--replace` push can see what the user changed on screen
+// BEFORE it wipes it (plan Phase C1). `guids` omitted ⇒ the whole deck.
+//
+// The ack's `tags` come from the Office.js tag API, NOT from the exported
+// bytes: exportAsBase64 strips custom tags (office-js #6104), so a slide's
+// drift BASELINE is recoverable only from `tags` — never from `base64`, which
+// carries the CURRENT state and nothing else. `deck.unmatched` lists the live
+// slides that are not in the requested set (what a whole-deck replace would
+// delete); `truncated` names GUIDs that matched but did not fit the relay
+// frame, to be re-requested.
+export async function exportSlides({
+  presId,
+  guids = null,
+  presentationId = null,
+  backendURL = null,
+}) {
+  if (!presId) throw new Error("exportSlides: presId is required");
+  const be = backendURL || (await resolveBackendForPres(presId));
+  const body = {};
+  if (Array.isArray(guids) && guids.length > 0) body.guids = guids;
+  if (presentationId) body.presentationId = presentationId;
+  const res = await bridgeFetch(
+    `/api/cli/presentations/${encodeURIComponent(presId)}/export-slides`,
+    {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify(body),
+      // Same pane round trip as the mutations (a suspended pane has to wake),
+      // and the payload is slide bytes.
+      timeoutMs:
+        parseInt(process.env.SLIDEMIND_BRIDGE_MUTATION_TIMEOUT_MS || "1805000", 10) ||
+        1805000,
+    },
+    be,
+  );
+  return ensurePaneAckOk(await res.json().catch(() => ({})), "export-slides");
+}
+
 export async function replaceSlides({
   presId,
   base64,
   operationId = null,
+  sourceTagsBySlide = null,
   backendURL = null,
 }) {
   if (!presId) throw new Error("replaceSlides: presId is required");
   if (!base64) throw new Error("replaceSlides: base64 is required");
   const be = backendURL || (await resolveBackendForPres(presId));
+  const replaceBody = { base64, operationId };
+  if (Array.isArray(sourceTagsBySlide) && sourceTagsBySlide.some(Boolean)) {
+    replaceBody.sourceTagsBySlide = sourceTagsBySlide;
+  }
   const res = await bridgeFetch(
     `/api/cli/presentations/${encodeURIComponent(presId)}/replace`,
     {
       method: "POST",
       headers: { "content-type": "application/json" },
-      body: JSON.stringify({ base64, operationId }),
+      body: JSON.stringify(replaceBody),
       timeoutMs:
         parseInt(process.env.SLIDEMIND_BRIDGE_MUTATION_TIMEOUT_MS || "1805000", 10) ||
         1805000,
@@ -3031,7 +3349,7 @@ export function pickPresentationEntry(
   const list = registry
     .map(
       (p) =>
-        `  ${p.presId}\t${p.env ? `[${p.env}]\t` : ""}${p.title || p.fileName || "(untitled)"}` +
+        `  ${p.presId}\t${p.env && isMultiEnv() ? `[${p.env}]\t` : ""}${p.title || p.fileName || "(untitled)"}` +
         (p.connected === false || p.suspendedAt ? "\t(suspended — PowerPoint in background)" : ""),
     )
     .join("\n");